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Purpose 

The change pages in this package correct technical errors identified in the 
current version of the iRIOU" 86 Release 6 documentation. 


Scope 

The following manuals are affected by this change package: 

Introduction and Operator's Reference Manual (146194-001) 
Programmer's Reference Manual, Part I (146195-001) 
Programmer's Reference Manual, Part II (146196-001) 
iRMX”* 86 Installation and Configuration Guide (146197-001) 


iRMX"* 86 Update Change Package Description 

The iRMX"* 86 OPERATING SYSTEM RELEASE 6 CHANGE PACKAGE: UPDATE 3 consists of a 
series of corrected pages that replace the corresponding pages in your 
documentation. A change package for iRi^X"* 86 Release 6 documentation is 
issued each quarter in conjunction with the iRNK"* 86 Release 6 Update 
Package. In addition to the change pages issued for the current update, each 
change package also contains an accumulation of the change pages from all 
previous updates . 

The change pages in this package are organized into sections according to the 
update in which they were issued. All change pages for the current update are 
in a section at the front of the package. Change pages from previous updates 
are in succeeding sections. 

Each update section begins with a blue cover and is subdivided into four 
segments, one for each of the iRMXT" 86 Release 6.0 documentation volumes. 

Each of these volume segments is identified by a yellow, pink, green, or 
orange cover sheet. Within each volume segment the change pages are organized 
in the sequence in which they occur in the volume. 

The Update Revision History pages — located immediately behind the sheet you 
are now reading — maintains a history of all changes distributed through the 
iRMy" 86 Release 6.0 Updates. This page indicates the product enhancement or 
the software problem report (SPR) that initiated each change. There is one 
Update Revision History page for each of the four iRNK"* 86 documentation 
volumes. 


Installation Instructions 


Change pages in the Update Package are accumulated from quarter to quarter. 

The change pages for each successive update are separated in this package by a 
blue cover page (similar to the sheet you are now reading). Within each 
update section, yellow, pink, green, and orange cover sheets segregate the 
change pages according to volume. 

The change pages in this package are installed by removing a page from your 
documentation and replacing it with the corresponding page from the change 
package. 

If this is the first iRtOP" 86 Release 6.gt Update to be installed in your 
documentation ; 


1. Immediately behind the change package cover sheet (the sheet you are 
now reading) are four Update Revision History pages — one for each of 
the four volumes of IRMX 86" Operating System documentation. Install 
each Update Revision History page in the front of the appropriate 
volume. 

2. Install all of the change pages in the package. Begin with the 
change pages issued for Update 2. (The Update 2 change pages are 
located in the bottom half of the package, behind the second blue 
cover sheet.) After installing the Update 2 change package, install 
the change pages for Update 3. (The Update 3 change pages are 
located immediately behind the sheet you are now reading.) You must 
install the Update 2 change package before installing the Update 3 
change package . If you were to install Update 2 last, you would risk 
replacing a current (Update 3) version of a page with an Update 2 
version of the same page. 

3. Fill out the Reader Comment Card — located at the bottom of the 
package — and mail it to Intel Corporation. 


If you have installed previous IRMX" 86 Release 6.0 Updates in your 
documentation ; 


1. Immediately behind the change package cover sheet (the sheet you are 
reading) are four Update Revision History pages — one for each of the 
four volumes of iRMX 86" Operating System documentation. In the 
front of each of your volumes, replace the Update History Pages from 
the previous update with the Update History Pages for Update 3. 

2. Install only the change pages for Update 3, These change pages are 
in the first section at the top of the package. 

3. Discard the remainder of the change pages in the change package. 
(These pages should already be in your documentaion if you installed 
the previous update.) 

4. Fill out the Reader Comment Card — located at the bottom of the 
package — and mail it to Intel Corporation. 
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ATTACHDEVICE 


ATTACHDEVICE 


This command attaches a physical device to the Operating System and 
associates a logical name with the device. The command catalogs the 
logical name in the root object directory, making the logical name 
accessible to all users. The format of the command is as follows: 



INPUT PARAMETERS 


physical name 


AS 

; logical name: 


NAMED 


PHYSICAL 


Physical device name of the device to be attached 
to the system. This name must be the name used in 
one of the Basic I/O System’s Device Unit 
Information Blocks (DUIB) , as defined at system 
configuration time (see Table 3-2). 

Preposition; required for the command. 

A 1-10 character string that represents the 
logical name to be associated with the device. 
Colons surrounding the logical name are optional; 
however, if you use colons, you must use matching 
colons . 

Specifies that the volume mounted on the device is 
already formatted for NAMED files. Examples of 
volumes that can contain named files are diskettes 
or hard disk platters. If neither NAMED nor 
PHYSICAL are specified, NAMED is the default. See 
the FORMAT command in this chapter for a further 
description of NAMED files. 

Specifies that the volume mounted on the logical 
device is considered to be a single, large file. 
Examples include line printers and terminals. See 
the FORMAT command in this chapter for a further 
description of PHYSICAL volumes. 
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ATTACHDEVICE 


WORLD Specifies that user ID WORLD (65535 decimal) is the 

owner of the device. This implies that any user can 
detach the device. If you omit this parameter, your 
user ID is listed as the owner of the device. In this 
case, only you and the system manager can detach the 
device. 


DESCRIPTION 

ATTACHDEVICE attaches a device to the sjrstem and catalogs a logical name 
for it in the root job’s object directory. The logical name is the means 
by which all users can access the device. Devices must have their 
characteristics listed in the Basic I/O System’s Device Unit Information 
Block (DUIB) at configuration time before they can be attached with the 
ATTACHDEVICE command. 

Table 3-2 and Table 3-3 list the physical device names normally used with 
the Basic I/O System. Your system might support a subset of these 
devices or it might support devices rot listed. If it supports the 
devices listed, it might support them under different names. Therefore, 
consult the person who configured your system to determine the correct 
device names for your system. 

One frequent use of the ATTACHDEVICE command is to attach a new device, 
such as a new disk drive or a line printer, without having to reconfigure 
portions of the Operating System. (See the DETACHDEVICE command in this 
chapter for a description of how to detach a device from the system 
without reconf igur ing . ) 

Unless you have a user ID of WORLD (65535) or specify the WORLD 
parameter, once you attach a device, only you and the system manager can 
detach the device. This limitation prevents users from detaching devices 
belonging to other users and prevents you from accidentally detaching 
system volumes. However, if you have a user ID of WORLD or specify the 
WORLD parameter, any device that you attach can be detached by any other 
user. Refer to the DETACHDEVICE command for more information. 

When the device attachment is completed, the ATTACHDEVICE command 
displays the following message: 

<physical name>, attached as <logical name>, id = <user id> 

where <physical name> and <logical name> are as specified in the 
ATTACHDEVICE command and <user id> is your user ID (or WORLD, if you 
specify the WORLD parameter) . 
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PATH 


This command lists the pathname of a data file or directory. 



INPUT PARAMETERS 

inpath-list The list of files whose pathnames you want to know. 

The default inpath-list file directory is the 
current working directory (:$:). 


ROOT Specifies that the pathname should start from the 

root directory of whatever device holds the file 
or directory. 


OUTPUT PARAMETERS 

TO Writes the pathnames of the input files to the 

specified output files. The specified output file 
or files should not already exist. If they do, 
PATH displays the following message: 

<pathname>, already exists, OVERWRITE? 

Enter Y, y, R, or r if you wish to write over the 
existing file. Enter an N (upper or lower case) 
or a carriage return alone if you do not wish to 
overwrite the existing file. In the latter case, 
the PATH command will pass over the corresponding 
input file, and will attempt to write the pathname 
of the next input file to the corresponding output 
file. 

If you specify multiple input files and a single 
output file, PATH appends the remaining input file 
pathnames to the end of the output file. 
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PATH 


OVER Writes the input Irile pathname over (replaces) the 

existing output files on a one-for-one basis, 
regardless of file size. If an output file does 
not already exist, the corresponding input file 
pathname is written to a new file with the 
corresponding output file name. If you specify 
multiple input files and a single output file, 
PATH appends the remaining input file pathnames to 
the end of the output file. 

AFTER Appends the input file pathname(s) to the current 

data in the existing output file or files. If the 
output file does not already exist, all listed 
input file pathnames will be concatenated into a 
new file with the listed output file name. 

outpath-list One or more pathnames for the output files. 


DESCRIPTION 

This command is useful for finding where you may be located within the 
file structure. The command gives the following listing when it is 
invoked with no input file listing: 


— PATH 

:sd: user /world 
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CONDITION CODE SUMMARY 


Table A-1. IRMXI 86 Condition Codes (continued) 


Hex. 

Value 

Mnemonic 

Manuals 
N B E L H 

Meaning 

Programmer Errors (continued) 

8004H 

E$PARAM 

***** 

A parameter which is neither a token 
nor an offset has an invalid value. 

8005H 

E$BAD$CALL 

* * 

The I/O System code has been damaged, 
probably due to a bug in an 
application task. Recovery is not 
possible. 

8006H 

E$ARRAY$- 

BOUNDS 

* 

Hardware or software has detected an 
array overflow. 

8007H 

E$NDP$- 

STATUS 

* 

An 8087 Numeric Processor Extension 
error has been detected; Operating 
System extensions can return the 
status of the 8087 to the exception 
handler. 

8008H 

E$ILLE6AL$- 

OPCODE 

* 

The iAPX 186 or 286 processor tried 
to execute an invalid instruction. 
(Software interrupt 6) 

8009H 

E$EMULATOR$- 

TRAP 

* 

The iAPX 186 or 286 processor tried 
to execute an ESC instruction with 
the •’emulator” bit set in the 
relocation register (iAPX 186) or the 
machine status word (iAPX 286). 

800AH 

E$INTERRUPT$- 

TABLE$LIMIT 

* 

An iAPX 286 LIDT instruction changed 
the interrupt table limit to a value 
between 20H and 42H. 

800BH 

E$CPUXFER$- 

DATA$LIMIT 

* 

For an iAPX 286 processor, the 
processor extension data transfer 
exceeded the offset of 0FFFFH in a 
segment . 

800CH 

E$SE6$WRAP$- 

AROUND 

* 

For an iAPX 286 processor, either a 
word operation attempted a segment 
wraparound at offset 0FFFFH; or a 
PUSH, CALL, or INT instruction 

attempted to execute while SP=1. 

N Nucleus Reference Manual 
B Basic I/O System Ref Manual 
E Extended I/O Sys Ref Manual 

L Loader Reference Manual 
H Human Interface Reference Manual 
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CONDITION CODE SUMMARY 


Table A-1. iRMXi 86 Condition Codes (continued) 


Hex. 

Mnemonic 

Manuals 

Meaning 

Value 


N B E L H 



Programmer Errors (continued) 


8017H 

E$CHECK$EX- 

CEPTION 

* 


A Pascal task has exceeded the bounds 
of a CASE statement. 

8021H 

E$NOUSER 

* * 

* 

No default user. 

8022H 

E$NOPREFIX 

* * 

* 

No default prefix. 

8040H 

E$NOT$LOG$- 

NAME 

* 

ic 

Specified object is not a device 
connection or file connection. 

8041H 

! 

E$NOT$- 

DEVICE 

* 


A token parameter referred to an 
existing object that is not, but 
should be, a device connection. 

8042H 

E$NOT$CON- 

NECTION 

* 


A token parameter referred to an 
existing object that is not, but 
should be, a file connection. 

806 0H 

E$JOB$PARAM 


* * 

The maximum job-size specified is 
less than the minimum job-size. 

8080H 

E$PARSE$- 

TABLES 


* 

There is an error in the internal 
parse tables. 

808 IH 

E$JOB$- 

TABLES 


* 

An internal Human Interface table was 
overwritten, causing it to contain an 
invalid value. 

8085H 

E$ERROR$- 

OUTPUT 


* 

The command invoked by C$SEND$COMMAND 
includes a call to C$SEND$EO$RESPONSE, 
but the command connection does not 
permit C$SEND$EO$RESPONSE calls. 


N Nucleus Reference Manual L Loader Reference Manual 

B Basic I/O System Ref Manual H Human Interface Reference Manual 

E Extended I/O Sys Ref Manual 


REPLACE 


Operator A-10 


UPDATE 3 


3/85 











This manual documents the Disk Verification Utility, a software tool that 
runs as a Human Interface command, verifying and modifying the data 
structures of iRMX 86 named and physical volumes. The manual describes 
the utility invocation and contains detailed descriptions of all utility 
commands. Also, because users must be familiar with the structure of 
iRMX 86 volumes to use the Disk Verification Utility features 
intelligently, the manual contains an appendix that describes the 
structure of iRMX 86 named volumes. 


READER LEVEL 


This manual is intended for system programmers who have had experience in 
examining actual volume information. It does not attempt to teach the 
user the proper procedures for examining and editing volume information. 


NOTATIONAL CONVENTIONS 


This manual uses the following conventions to illustrate syntax. 

UPPERCASE Uppercase information must be entered exactly as 

shown. You can, however, enter this information in 
uppercase or lowercase. 

lowercase Lowercase fields contain variable information. You 

must enter the appropriate value or symbol for 
variable fields. 


underscore In examples of dialog at the terminal, user input is 

underscored to distinguish it from system output. 

<variable> Whenever an error message or the output resulting 

from a DISKVERIFY command contains a variable part, 
that variable part is enclosed in angle brackets < >. 


Also, this manual uses the "’railroad track” schematic to illustrate the 
syntax of the disk verification commands. This syntax consists of what 
looks like an aerial view of a model railroad setup, with syntactic 
elements scattered along the track. To interpret the command syntax, you 
start at the left side of the schematic, follow the track through all the 
syntactic elements you desire (sharp turns and backing up are not 
allowed), and exit at the right side of the schematic. The syntactic 
elements that you encounter, separated by spaces, comprise a valid 
command. For example, a command that consists of a command name and two 
optional parameters would have the following schematic representation: 
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You could enter this command in any of the following forms: 

COMMAND 
COMMAND paraml 
COMMAND param2 
COMMAND paraml param2 

The arrows indicate the possible flow through the tracks; they are 
omitted in the remainder of the manual. 
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CHAPTER 1 

INVOKING THE DISK VERIFICATION UTILITY 


In the process of using an IRMX 86 application system, you may have 
occasion to store data on secondary storage devices, sometimes large 
amounts of data. Due to the nature of secondary storage devices, 
unforseen circumstances such as power irregularities or accidental reset 
may destroy information on these devices, causing them to be inaccessible 
to your iRMX 86 system. In some cases, the loss of only a small amount 
of data can render an entire volume, such as a disk, useless. 

In such cases, it is desirable to have a mechanism to examine and modify 
the damaged volume. This mechanism would allow you to determine how much 
of the information on the volume was damaged. It would also allow you to 
recreate file structures on the damaged volume so that you could salvage 
some of the valid data. The iRMX 86 disk verification utility is a tool 
that allows you to perform these functions. 

The disk verification utility verifies the data structures of iRMX 86 
physical and named volumes. It can also be used to reconstruct the free 
fnodes map, the volume free space map, and the bad blocks map of the 
volume and perform absolute editing. 

You can use the disk verification utility in one of two ways: 

o As a single command which verifies the structures of a volume and 
returns control to the Human Interface. 

o As an interactive program which allows you to check and modify 
information on the volume by entering individual disk 
verification commands. 

To take full advantage of the capabilities of the disk verification 
utility, you must be familiar with the structure of iRMX 86 named 
volumes. Appendix A contains detailed information about the volume 
structure. If you are unfamiliar with the iRMX 86 volume structure, you 
should avoid using the individual disk verification commands. When used 
carelessly, these commands can make your volumes unusable. 

However, even if you know nothing about iRMX 86 volume structures, you 
can still use the utility as a single command to verify that the data 
structures on an iRMX 86 volume are valid. 
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INVOKING THE DISK VERIFICATION UTILITY 


INVOCATION 

The format of the Human Interface command used to invoke the disk 
verification utility is as follows: 



where : 


: logical-name: Logical name of the secondary storage device 

containing the volume. 

TO Copies the output from the disk verification 

utility to the specified file. If no preposition 
is specified » TO :CO: is the default. 

OVER Copies the output from the disk verification 

utility over the specified file. 

AFTER Appends the output from the disk verification 

utility to the end of the specified file. 

outpath Pathname of the file to receive the output from the 

disk verification utility. If you omit this 
parameter and the: TO/OVER/ AFTER preposition, the 

utility copies the output to the console screen (TO 
:CO:). You cannot direct the output to a file on 
the volume being verified. If you attempt this, 
the utility returns an E$NOT_CONNECTION error 
message. 
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INVOKING THE DISK VERIFICATION UTILITY 


DISK 


VERIFY or 


NAMEDl or 


NAMED or 


ALL 


NAMED2 or 


Displays the attributes of the volume being verified. 

If you specify this parameter, the utility performs 
the disk function and returns control to you at the 
Human Interface level. You can then enter any Human 
Interface command provided that the device verified 
is not the system device. Refer to the description 
of the DISK command in Chapter 2 for more 
information. Any parameter after this one is 
ignored . 

V Performs a verification of the volume. This 

verification function and the associated options are 
described in detail in the ’’VERIFY Command” section 
of Chapter 2. If you specify this parameter and 
omit the options, the utility performs the NAMED 
verification. 

If you specify this parameter, the utility performs 
the verification function and returns control to you 
at the Human Interface level. You can then enter 
any Human Interface command if the device is not the 
system device (:sd:). 

If you omit this parameter and the DISK parameter, 
the utility displays a header message and the 
utility prompt (*) . You can then enter any of the 
disk verification commands listed in Chapter 2. 

N1 VERIFY option that applies to named volumes only. 

This option checks the fnodes of the volume to 
ensure that they match the directories in terms of 
file type and file heirarchy. This option also 
checks the information in each fnode to ensure that 
it is consistent. Refer to the description of the 
VERIFY command in Chapter 2 for more information. 

f VERIFY option that performs both the NAMEDl and 

NAMED2 verification functions on a named volume. If 
you omit the VERIFY option, NAMED is the default 
option . 

VERIFY option that applies to both named and 
physical volumes. For named volumes, this option 
performs both the NAMED and PHYSICAL verification 
functions. For physical volumes, this option 
performs the PHYSICAL verification function. 

N2 VERIFY option that applies to named volumes only. 

This option checks the allocation of fnodes on the 
volume, checks the allocation of space on the 
volume, and verifies that the fnodes point to the 
correct locations on the volume. Refer to the 

description of the VERIFY command in Chapter 2 for 
more information. 
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INVOKING THE DISK VERIFICATION UTILITY 


PHYSICAL VERIFY option that applies to both named and 

physical volumes. This option reads all blocks on 
the volume and checks for I/O errors. 

LIST VERIFY option that you can use with those VERIFY 

parameters that, either explicitly or implicitly, 
specify the NAMEDl parameter. When you use this 
option, the file information generated by VERIFY is 
displayed for every file on the volume, even if the 
file contains no errors. Refer to the description 
of the VERIFY command in Chapter 2 for more 
information. 


OUTPUT 


When you enter the DISKVERIFY command, the utility responds by displaying 
the following line: 

iRMX 86 DISK VERIFY UTILITY, Vx.x 
Copyright <year> Intel Corporation 

where Vx.x is the version number of the utility. If you specify the 
VERIFY or V parameter in the DISKVERIFY command, the utility performs a 
verification of the volume and copies the verification information to the 
console (or to the file specified by the outpath parameter). The 
verification information is the same as that produced by the VERIFY 
utility command. Refer to the description of the VERIFY command in 
Chapter 2 for a description of the verification output. After generating 
the verification output, the utility returns control to the Human 
Interface, which prompts you for more Human Interface commands. The 
following is an example of such a DISKVERIFY command: 

- DISKVERIFY :F1: VERIFY NAMED2 
iRMX 86 DISK VERIFY UTILITY , Vx.x 
Copyright <year> Intel Corporation 

DEVICE NAME = wfd0 : DEVICE SIZE = 0003E900 : BLOCK SIZE = 0080 

• NAMED2 * VERIFICATION 
BIT MAPS O.K. 


However, if you omit the VERIFY (or V) parameter from the DISKVERIFY 
command, the utility does not return control to the Human Interface. 
Instead, it issues an asterisk (*) as a prompt and waits for you to enter 
individual DISKVERIFY commands. The following is an example of such a 
DISKVERIFY command: 

- DISKVERIFY :F1: 

iRMX 86 DISK VERIFY UTILITY , Vx.x 
Copyright <year> Intel Corporation 
* 


REPLACE 


Disk Verify 1-4 


UPDATE 


3, 


3/85 



SUBSTITUTEWORD 


EXAMPLE (continued) 

* SUBSTITUTEWORD<cr> 

0000: A0B0 - 0000<cr> 
0002: 8070 - <cr> 
0004: E511 - <cr> 
0006: FFFF - 3111<cr> 
0008: FFFF - .<cr> 


* SUBSTITUTEWORD 35<cr> 

0035: 0000 - E6FF<cr > 
0037: 0000 - E6AB<cr> 
0039: 0000 - .<cr> 

* 
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VERIFY 


VERIFY COMMAND 

This command checks the structures on the volume to determine whether the 
volume is properly formatted. You can abort this command by typing a 
CONTROL-C (press the CONTROL key, and while holding it down, press the C 
key). The format of the VERIFY command is: 



INPUT PARAMETERS 

NAMEDl or N1 Checks named volumes to ensure that the information 

recorded in the fnodes is consistent and matches 
the information obtained from the directories 
themselves. VERIFY performs the following 
operations during a NAMEDl verification: 

• Checks fnode numbers in the directories to see 
if they correspond to allocated fnodes. 

• Checks the parent fnode numbers recorded in the 
fnodes to see if they match with the information 
recorded in the directories. 

• Checks the fnodes against the files to determine 
if the fnodes specify the proper file type. 

• Checks the POINTER(n) structures of long files 
to see if the indirect blocks accurately reflect 
the number of blocks used by the file. 

• Checks each fnode to see if the TOTAL SIZE, 
TOTAL BLKS, and THIS SIZE fields are consistent. 

• Checks the bad blocks file to see if the blocks 
in the file correspond to the blocks marked as 
’’bad" on the volume. 
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STRUCTURE OF iRMX4 86 NAMED VOLUMES 


If the formatting program is unable to provide this 
information, it places an ASCII space in this field. 

• The next two bytes contain a two-digit ASCII 
sequence number which is incremented by the 
formatting program each time the formatting 
program changes in a way that affects the volume 
format. The Release 4 FORMAT Human Interface 
command places the characters ”00** in this field. 

• The right-most three bytes of the field contain 

a three-digit ASCII number specifying the 
version of the Basic I/O System that was used in 
formatting the volume (for example, the 

characters **030” would indicate version 3.0). 
If the formatting program is unable to obtain 
this information, it places ASCII spaces in this 
field. 

DEVICE$SPECIAL(8) Reserved for special device-specific information. 

When no device-specific information exists, this 
field must contain zeros. If the device is a 
Winchester disk with an iSBC 215 controller or if 
the device is a disk with an iSBC 220 controller, 
the iRMX 86 Operating System imposes a structure on 
this field and supplies the following information: 


SPECIAL 

STRUCTURE ( 

CYLINDERS 

WORD, 

FIXED 

BYTE, 

REMOVABLE 

BYTE, 

SECTORS 

BYTE, 

SECTOR_SIZE 

WORD, 

ALTERNATES 

BYTE) ; 

where : 

CYLINDERS 

Total number of cylinders on the 
drive. 

FIXED 

Number of heads on the fixed 
disk or Winchester disk. 

REMOVABLE 

Number of heads on the removable 
disk cartridge. 

SECTORS 

Number of sectors in a track. 

SECTOR_SIZE 

Sector size, in bytes. 

ALTERNATES 

Number of alternate cylinders. 


The remainder of the Volume Label (bytes 440 through 511) is reserved and 
must be set to zero. 
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STRUCTURE OF iRMX4 86 NAMED VOLUMES 


INITIAL FILES 

Any mechanism that formats IRMX 86 named volumes must place seven files 
on the volume during the format process. These seven files are the fnode 
file, the volume label file, the volume free space map file, the free 
f nodes map file, the bad blocks file, the root directory, and the space 
accounting file. The first of these files, the fnode file, contains 
information about all of the files on the volume. The general structure 
of the fnode file is discussed first. Then all of the files are 
discussed in terms of their fnode entries and their functions. 


FNODE FILE 

A data structure called a file descriptor node (or fnode) describes each 
file in a named file volume. All the f nodes for the entire volume are 
grouped together in a file called the fnode file . When the I/O System 
accesses a file on a named volume, it esxamines the iRMX 86 Volume Label 
(described in the previous section) to determine the location of the 
fnode file, and then examines the appropriate fnode to determine the 
actual location of the file. 

When a volume is formatted, the fnode file contains seven allocated 
fnodes and any number of un-allocated fnodes. The original number of 
un-allocated fnodes depends on the FILES parameter of the FORMAT 
command. These allocated fnodes represent the fnode file, the volume 
label file, the volume free space map file, the free fnodes map file, the 
bad blocks file, the root directory, and the space accounting file. 
Later sections of this chapter describe these files. The size of the 
fnode file is determined by the number of fnodes that it contains. The 
number of fnodes in the fnode file also determines the number of files 
that can be created on the volume. The number of files is set when you 
format the storage medium. 

The structure of an individual fnode in a named file volume is as follows: 
DECLARE 

FNODE STRUCTUREC 


FLAGS 

WORD, 

TYPE 

BYTE, 

GRAN 

BYTE, 

OWNER 

WORD, 

CR$TIME 

DWORD, 

ACCESSiTIME 

DWORD, 

MOD$TIME 

DWORD, 

TOTAL$SIZE 

DWORD, 

TOTAL$BLKS 

DWORD, 

POINTRC40) 

BYTE, 

THIS$SIZE 

DWORD, 

RESERVED$A 

WORD, 

RESERVED$B 

WORD, 

ID$COUNT 

WORD, 

ACC(9) 

BYTE, 

PARENT 

WORD, 

AUX(*) 

BYTE) ; 
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MEMORY MANAGEMENT 


MOVEMENT OF MEMORY BETWEEN JOBS 

When a task tries to create a segment (or an object of any other type), 
and the unallocated part of its job's pool is not sufficient to satisfy 
the request, the Nucleus tries to borrow more memory from the job's 
parent (and then, if necessary, from its parent's parent, and so on). 
Such borrowing increases the pool size of the borrowing job and is thus 
restricted by the pool maximum attribute of the borrowing job. 

When a job is deleted, the memory in its pool becomes unallocated, and 
access to it is given back to the parent job. The smallest contiguous 
piece of memory that a job may borrow from its parent is a configuration 
parameter. The subject of configuration is covered in the iRMX 86 
CONFIGURATION GUIDE. 

Observe that, if a job has equal pool minimum and pool maximum 
attributes, then its pool is fixed at that common value. This means 
that, once it has this amount, the job may not borrow memory from its 
parent . 


MEMORY ALLOCATION 


The memory pool of a job consists of two classes of memory: allocated 
and unallocated. Memory in a job is unallocated unless it has been 
requested, either explicitly or implicitly, by tasks in the job or unless 
it is on loan to a child job. A task's request for memory is explicit 
when it calls the CREATE$SEGMENT system call. A request is implicit when 
the task attempts to create any type of object other than a segment. 

The Nucleus borrows small amounts of memory from a job's pool each time a 
task in that job creates an object. This memory is needed for bookkeeping 
purposes. When the object is deleted, the borrowed memory is returned to 
the pool. Appendix B lists these memory requirements. 

When a task no longer needs a segment, it can return the segment to the 
unallocated part of the job's pool by using the DELETE$ SEGMENT system 
call. Figure 5-2 shows how memory "moves". 
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MEMORY MANAGEMENT 



x-145 


Figure 5-2. Memory Movement Diagram 


SYSTEM CALLS FOR SEGMENTS 


The following system calls manipulate segments: 

• create! SEGMENT creates a segment and returns a token for it. 

• delete! SEGMENT returns a segment to the pool from which it 

was allocated. 

• GET!S1ZE returns the size, in bytes, of a segment. 

• SET!P00L!MIN enables a task to change the pool minimum 

attribute of its job’s pool. 

• GET!P00L!ATTRIB returns the following memory pool attributes 

of the calling task's job: pool minimum, pool maximum, initial 

size, number of allocated paragraphs, and number of available 
paragraphs . 
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ACCEPTSCONTROL 


CONDITION CODES 
E$OK 
E$BUSY 

E$CONTEXT 

E$EXIST 

E$NOT$CONFIGURED 

E$TYPE 


No exceptional conditions. 

Another task currently has access to the protected 
data. 

The calling task currently has access to the region 
in question. 

The region parameter is not a token for an existing 
object. 

This system call is not part of the present 
configuration. 

The region parameter is a token for an object that 
is not a region. 
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ALTERSCOMPOSITE 


ALTER$COMPOSITE 

The ALTER$COMPOSITE system call replaces components of composite objects. 


CAUTION 


Composite objects require the creation 
of extension objects. Jobs that create 
extension objects cannot be deleted 
until all the extension objects are 
deleted. Therefore you should avoid 
creating composite objects in Human 
Interface applications. If a Human 
Interface application creates extension 
objects, the application cannot be 
deleted asynchronously (via a CTRL/c 
entered at a terminal). 


CALL RQ$ALTER$COMPOSITE( extension, composite, component! index, 

replacinglobj , except$ptr) ; 


INPUT PARAMETERS 


extension 


A TOKEN for the extension type object corresponding 
to the composite object being altered. 


composite A TOKEN for the composite object being altered. 

component! index A WORD whose value specifies the location (starting 

at 1) in the component list of the component to be 
replaced. 

replacing!obj A TOKEN for the replacement component object or 

zero, which represents no object. 


OUTPUT PARAMETER 

except!ptr A POINTER to a WORD to which the iRMX 86 Operating 

System will return the condition code generated by 
this system call. 
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CREATE$JOB 


max$ tasks 


max$priority 


except$handler 


A WORD that specifies the maximum number of tasks 
that can exist simultaneously in the new job. 

• If not 0FFFFH, it contains the maximum number of 
tasks that can exist simultaneously in the new 
job. 

• If 0FFFFH, it indicates that there is no limit 
to the number of tasks that tasks in the new job 
can create. 

• It cannot be zero. A value of 0H will produce 
the E$LIMIT exception. 

A BYTE that sets an upper limit on the priority of 
the tasks created in the new job. 

• If not zero, it contains the maximum allowable 
priority of tasks in the new job. If 
max$priority exceeds the maximum priority of the 
parent job, an E$LIMIT error occurs. 

• If zero, it indicates that the new job is to 

inherit the maximum priority attribute of its 
parent job. 

A POINTER to a structure of the following form: 
STRUCTURE ( 

EXCEPTION$HANDLER$PTR POINTER, 

EXCEPTION$MODE BYTE) ; 

If exception$handler$ptr is not zero, then it is a 

POINTER to the first instruction of the new job*s 
own exception handler. If exception$handler$ptr is 
zero, the new job’s exception handler is the system 
default exception handler. In both cases, the 

exception handler for the new task becomes the 
default exception handler for the job. The 

exception$mode indicates when control is to be 
passed to the exception handler. It is encoded as 
follows: 


Value 


0 

1 

2 

3 


When Control Passes 
To Exception Handler 

Never 

On programmer errors only 
On environmental conditions only 
On all exceptional conditions 
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CREATE$JOB 



job$flags A WORD containing information that the Nucleus 

needs to create and maintain the job. The bits 
(where bit 15 is the high-order bit) have the 
following meanings: 

bit meaning 

15-2 reserved. 

1 If 0» then whenever a task in the new job 
or any of its descendant jobs makes a 
Nucleus system call, the Nucleus will 
check the parameters for validity. 

If 1, the Nucleus will not check the 
parameters of Nucleus system calls made 
by tasks in the new job. However, if any 
ancestor of the new job has been created 
with this bit set to 0, there will be 
parameter checking for the new job. 

0 reserved. 

task$priority A BYTE that controls the priority of the new job’s 

initial task. 


• If not zero, it contains the priority of the new 
job's initial task. If the task$priority 
parameter is greater (numerically smaller) than 
the new job's maximum priority attribute, an 
E$PARAM error occurs. 

• If zero, it indicates that the new job's initial 
task is to have a priority equal to the new 
job's maximum priority attribute. 

start$address A POINTER to the first instruction of the new job's 

initial task (the task created with the job). 

data$seg A WORD or SELECTOR that specifies v^diich data 

segment the new job's initial task is to use. 

• If not zero, it contains the base address of the 
data segment of the new job's initial task. 

• If zero, it indicates that the new job's initial 
task assigns its own data segment. Refer to the 
iRMX 86 CONFIGURATION GUIDE for more information 
about data segmc^nt allocation. 
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CREATE$SEMAPHORE 


CONDITION CODES 
E$OK 
E$LIMIT 

E$MEM 

E$NOT$CON- 

FIGURED 

E$PARAM 


No exceptional conditions. 

The calling task’s job has already reached its 
object limit. 

The memory available to the calling task's job is 
not sufficient to create a semaphore. 

This system call is not part of the present 
configuration. 

At least one of the following is true: 

• The initial$value parameter is larger than the 
maximum$value parameter. 

• The maximum$value parameter is 0. 
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CREATE$TASK 

CREATE$TASK creates a task. 


task = RQ$CREATE$TASK (priority, start$address , data$seg, stack$ptr, 

stack$size, task$flags, except$ptr) ; 


INPUT PARAMETERS 


priority 


start$address 

data$seg 


stack$ptr 


A BYTE that specifies the priority of the new task. 

• If not zero, it contains the priority of the new 
task. The priority parameter must not exceed 
the maximum allowable priority of the calling 
task's job. If it does, an E$PARAM error occurs. 

• If zero, it indicates that the new task's 
priority is to equal the maximum allowable 
priority of the calling task's job. 

A POINTER to the first instruction of the new task. 

A WORD or SELECTOR that specifies the new task's 

data segment. 

• If not zero, the WORD contains the base address 
of the new task's data segment. 

• If zero, the WORD indicates that the new task 
assigns its own data segment. Refer to the iRMX 
86 CONFIGURATION GUIDE for further information 
on data segment allocation. 

A POINTER that specifies the location of the stack 

for the new task. 


• If the base portion is not zero, the Nucleus 
uses the sum of the offset portion and the 
stacks ize parameter (declared during the call to 
CREATE$TASK) as the value of the SP register 
(the stackpointer) . 

• If the base portion is zero, the Nucleus 
allocates a stack to the new task. The length 
of the stack is equal to the value of the 
stack$size parameter. 
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CREATE$TASK 


stack$size 


task$f lags 


OUTPUT PARAMETERS 
task 

except$ptr 


REPLACE 


A WORD containing the size, in bytes, of the new 
task's stack segment. The stack size must be at 
least 16 bytes. The Nucleus increases specified 
values that are not multiples of 16 up to the next 
higher multiple of 16. 

The stack size should be at least 300 bytes if the 
new task is going to make Nucleus system calls. 
Refer to the iRMX 86 PROGRAMMING TECHNIQUES manual 
for further information on assigning stack sizes. 

If you set the stack$ptr parameter to indicate a 
user-provided stack, setting the stack$size 
parameter causes the Nucleus to fill the 

user-provided stack with special characters which 
the iRMX 86 Debugger uses to detect stack 

overflow. Because of this situation, never specify 
a stack$size value that is larger than size of the 
user-provided stack. 

A WORD containing information that the Nucleus 
needs to create and maintain the task. The bits 
(where bit 15 is the high-order bit) have the 
following meanings: 

Bits Meaning 

15-1 Reserved bits which should be set to 

zero 

0 If one, the task contains 

floating-point instructions. These 
instructions require the NPX component 
for execution 

If zero, the task does not contain 
floating-point instructions 


A TOKEN to which the Operating System will return a 
token for the new task. 

A POINTER to a WORD to which the iRMX 86 Operating 
System will return the condition code generated by 
this system call. 


Nucleus 12-39 


UPDATE 3 , 


3/85 


CREATE$TASK 


DESCRIPTION 

The CREATE$TASK system call creates a task and returns a token for it. 
The new task counts as one against the object and task limits of the 
calling task's job. Attributes of the new task are initialized upon 
creation as follows: 

• priority; as specified in the call. 

• execution state: ready. 

• suspension depth: 0. 

• containing job: the job which contains the calling task. 

• exception handler: the exception handler of the containing job. 

• exception mode: the exception mode of the containing job. 



EXAMPLE 


/**5ic*:<c***:<f***J>cii>c****)«c)«c***:*f)«c)«(***5«t*****5ic***iir***********5>c**)ic5ic*y^**5>o>c*2«c****yc*:*c)Sc 

* This example illustrates how the CREATE$TASK system call can be * 

* used. * 

*5<C***)IC*?«{)«t***********5lC*******ilf*)«C)«C:<C****2lC)>C:l::«C*5«C)*C*5>(***5*C*5lC***)»C*)«0*C***)IC*)IC*5«C5«C*:«C5«C)>C/ 


$INCLUDE(: FI; SAMPLE. EXT); /* Declares all system calls */ 


TASK_CODE: PROCEDURE EXTERNAL; 
END TASK_CODE; 


DECLARE TOKEN LITERALLY 'SELECTOR*; 

/* if your PL/M compiler does not 
support this variable type, 
declare TOKEN a WORD */ 


DECLARE 

task$token 

TOKEN; 

DECLARE 

priority$level$66 

LITERALLY 

DECLARE 

start$address 

POINTER; 

DECLARE 

data$seg 

WORD; 

DECLARE 

stack$po inter 

POINTER; 

DECLARE 

stack$size$512 

LITERALLY 

DECLARE 

task$f lags 

WORD; 

DECLARE 

status 

WORD; 


' 66 * 


*512* 


» 


/* new task's stack 
size is 512 bytes */ 


SAMPLE_PROCEDURE : 

PROCEDURE; 

start$address = @TASK_CODE; 
data$seg = 0; 
stack$pointer = 0; 
task$flags = 0; 


/* first instruction of the new task */ 
/* task sets up own data segment */ 

/* automatic stack allocation */ 

/* designates no floating-point 
instructions */ 
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DELETE$COMPOSITE 


EXAMPLE 

See the example in section ’’The Initialization Part” of Chapter 11. 


CONDITION CODES 
E$OK 

E$CONTEXT 


E$MEM 


No exceptional conditions. 

At least one of the following is true: 

• The extension type does not match the 
composite parameter. 

• One or both of the extension or composite 
parameters is not a token for an existing 
object. 

• One or both of the extension or composite 
parameters is a token for an object that is 
not of the correct type. 

The memory available to the calling task’s job is 
not sufficient to complete this operation. 


E$NOT$CONFIGURED This system call is not part of the present 

configuration. 
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DELETESEXTENSION 


DELETE$EXTENSION 

The DELETE$ EXTENSION system call deletes an extension object and all 
con^osites of that type. 


CAUTION 


Jobs that create extension objects 
cannot be deleted until the extension 
object is deleted. Therefore, you 
should avoid creatinjj extension objects 
in Human Interface applications. If a 
Human Interface application creates 
extension objects, the application 
cannot be deleted asjmchronously (via a 
CTRL/c entered at a terminal). 



CALL RQ$DELETE$EXTENSION( extension, except$ptr) ; 


INPUT PARAMETER 
extension 


A TOKEN for the extension object to be deleted. 


OUTPUT PARAMETER 

except$ptr A POINTER to a WOEiD to which the iRMX 86 Operating 

System will return the condition code generated by 
this system call. 


DESCRIPTION 

The DELETE$EXTENSION system call deletes the specified extension object 
type and all composite objects of that type. This makes the 
corresponding type code available for reuse. 

If a deletion mailbox was specified when the extension type was created, 
then all of the composite objects created by the extension type to be 
deleted are sent to that deletion mailbox. In this case, this call will 
not be completed until all of the composite objects have been deleted. 

If the extension type has no deletion mailbox, the composite objects 
created by the extension type to be deleted are deleted without informing 
the type manager. 
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DELETE$TASK 


o 

o Typical PL/M-86 Statements 

o 

/******1»{2fc*yt******lV:k*)llC**5l{****5«C*)>cyi{)>{*yc*5«{5«C******5lC*5«C***)<C)«C**2>{l/i(***1>C)«C*VIC)*C*Vlt***Vit*** 

* The calling task has created a task (whose code is labeled * 

* TASK_CODE) which is not an interrupt task. When this task is no * 

* longer needed, it may be deleted by any task that knows its token. * 

CALL RQ$DELETE$TASK (task$token, 

^status) ; 
o 

o Typical PL/M-86 Statements 

o 

END SAMPLE_PROCEDURE;; 


CONDITION CODES 
E$OK 

E$CONTEXT 

E$EXIST 


E$NOT$CON- 

FIGURED 

E$TYPE 


No exceptional conditions. 

The task parameter is a token for an interrupt task. 

One of the following conditions has occurred: 

• The task parameter is not a token for an 
existing object. 

• The task parameter represents a task whose job 
is being deleted. 

• More than one task is trying to delete a task 
which is in a region. 

This system call is not part of the present 

configuration. 

The task parameter is a token for an object which 

is not a task. 
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DISABLE 


DISABLE disables an interrupt level. 


CALL RQ$DISABLE ( level « except$ptr) ; 


INPUT PARAMETER 

level A WORD that specifies an interrupt level that is 

encoded as follows (bit 15 is the high-order bit): 

Bits Valu e 

15-7 0 

6-4 First digit of the interrupt level (0-7) 

3 If one., the level is a master level and 

bits 6-4 specify the entire level number 

If zero, the level is a slave level and 
bits 2-0 specify the second digit 

2-0 Second digit of the interrupt level 

(0-7), if bit 3 is zero 


OUTPUT PARAMETER 

except$ptr A POINTER to a WOBlD to which the iRMX 86 Operating 

System will return the condition code generated by 
this system call. All exceptional conditions must 
be processed in-line. Control does not pass to an 
exception handler. 


DESCRIPTION 

The DISABLE system call disables the specified interrupt level. It has 
no effect on other levels. To be disabled, a level must have an 
interrupt handler assigned to it. Otherwise, the Nucleus returns an 
exception code. 

You must not disable the level reserved for the system clock. You 
determine this level during system configuration (refer to the iRMX 86 
CONFIGURATION GUIDE). 
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FORCE$DELETE 


DESCRIPTION 

The FORCE$DELETE system call deletes objects whose disabling depths are 
zero or one. If an object has a deletion depth of two or more, the 
calling task is put to sleep until the deletion depth is decreased to 
one. At that time, the object is deleted and the task is awakened. If 
the wrong extension type is specified, FORCE$DELETE issues and E$CONTEXT 
error and returns without deleting the composite. 


CONDITION CODES 
E$OK 

E$ CONTEXT 

E$EXIST 

E$MEM 

E$NOT$CONFIGURED 

E$TYPE 


No exceptional conditions. 

The wrong extension type was used in the extension 
parameter of the FORCE$DELETE system call. 

One or both of the object or extension parameters 
is not a token for an existing object. 

The memory available to the calling task’s job is 
not sufficient to complete this call. 

This system call is not part of the present 
conf iguration . 

The extension parameter is a token for an object 
that is not an extension object. 




REPLACE 


Nucleus 12-81 


UPDATE 


3 


3/85 


GET$ EXCEPT ION$HANDLER 

GET$EXCEPTION$HANDLER returns information about the calling task’s 
exception handler. 


CALL RQ$GET$EXCEPTION$HANDLER ( except ion$ inf o$ptr, except$ptr) ; 


OUTPUT PARAMETERS 


except ion$ inf o$ptr A POINTER to a strxicture of the following form: 


STRUCTURE ( 

EXCEPTION$IMJNDLER$OFFSET WORD, 
EXCEPTION$H#MDLER$BASE WORD, 

EXCEPTION$MODE BYTE) ; 


where, after the call, 

• except ion$handler$off set contains the offset of 
the first instriiction of the exception handler. 

• exception$handler$base contains a base for the 
segment containing the first instruction of the 
exception handler. If exception$handler$base 
and exception$handler$of fset are both zero, the 
calling task’s exception handler is the system 
default exception handler. 

• except ion$mode contains an encoded indication 

of the calling task’s current exception mode. 

The value is interpreted as follows: 

When to Pass Control 
Value to Exception Handler 

0 Never 

1 On programmer errors only 

2 On environmental conditions only 

3 On all exceptional conditions 


except$ptr A POINTER to a WORD to which the iRMX 86 Operating 

System will return the condition code generated by 
this system call. 


DESCRIPTION 

The GET$EXCEPTION$HANDLER system call returns both the address of the 
calling task’s exception handler and the current value of the task’s 
exception mode. 
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GET$TYPE 

GET$TYPE returns the encoded type of an object. 


type$code = RQ$GET$TYPE (object, except$ptr) ; 


INPUT PARAMETER 

object A TOKEN for an object. 


OUTPUT PARAMETERS 


type$code 


except$ptr 


A WORD which contains the encoded type of the 
specified object. The types for iRMX 86 objects 
are encoded as follows: 


Value Type 


1 

2 

3 

4 

5 

6 
7 

100H 

101H 

300H 

301H 

8000H - 0FFFFH 


job 

task 

mailbox 

semaphore 

region 

segment 

extension 

composite (user) 

composite (connection) 

composite (I/O job) 

composite (logical device) 

user-created composites 


Users and connections are described in the iRMX 86 
BASIC I/O SYSTEM REFERENCE MANUAL. I/O jobs and 
logical devices are described in the iRMX 86 
EXTENDED I/O SYSTEM REFERENCE MANUAL. 


A POINTER to a WORD to which the condition code for 
the call is returned. 


I 


DESCRIPTION 

The GET$TYPE system call returns the type code for an object. 
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Vat I5>l YKt 


EXAMPLE 


/******l»c***3«c****1*c***)«c******i>c*********)*c**5lc***5lc*>«nt:**5>c***********3«c5>tvic5«c**5«c**:«cyc 

* This example illustrates how the GETJ^TYPE system call can be used * 

* to return the encoded type of an object. * 

****5»C*:*f2«CllcViC***)k*2«C)<(****5«tllt*******)IC**)>t2«t***3>CllC)IIC5«C>iC*)«C***5lC****lfc**yC5«C*********)IC5«C*yc:<C / 


$INCLUDE ( : FI : SAMPLE . EXT ) ; 


Declares all system calls */ 


DECLARE TOKEN 


DECLARE type$code 
DECLARE mbx$ token 
DECLARE calling$tasks$job 
DECLARE wait$forever 
DECLARE object$token 
DECLARE response 
DECLARE status 


LITERALLY ’SELECTOR*; 

/i< if your PL/M compiler does not 
support this variable type, 
declare TOKEN a WORD */ 

WORD; 

TOKEN; 

LITERALLY ’ 0 ’ ; 

LITERALLY ’0FFFFH* ; 

TOKEN; 

TOKEN ; 

WORD; 


SAMPLE_PROCEDURE : 

PROCEDURE; 

• Typical PL/M-86 Statements 

/****)>f********)IC5>t**5lC*jlC*5k5«C*3«C*)«C*)*{1>C*****5>t**)IC:<C*******5«C*)>C**5lC***)>C)>C5«C**:*C***)<C**)>C:«C)«C* 

* In order to invoke the GET$TYPE system call, the calling task must * 

* have the token for an object. In this example, the calling task * 

* invokes the LOOKUP$OBJECT system call and then the RECEIVE$MESSAGE * 

* system call to receive the token for an object of unknown type * 

* ( obj ect$ token ) . * 

*ilc*********:fc*:k^>c:fc*:lt*****:fc**5>c****ilc3>c5ic*****:lr***)>c**5ic**5>c*5>c:(ici>c:*c*2>c**:*(**2>c*5lc***)>c:/ic*:<c/ 


mbx$token = RQ$LOOKUP$OBJECT (calling$tasks$job, 

0(3, *MBX’), 
wait$forever, 
@£itatus) ; 


• Typical PL/M-86 Statements 


* The RECEIVE$MESSAGE system call returns object$token to the calling * 

* task after the calling task invoked LOOKUP$OBJECT to receive the * 

* token for the mailbox named ’MBX* . *MBX* had been predesignated * 

* as the mailbox another task would us€i to send an object. * 

**********5lc**5lc5>c*5lc*)«c:«c)<cyc**5»c****)«c5«c********)>:**5>0«c**yc*****5>c:*n«c*)lc)»c)>c5«c****5lc*)lc*)«c5lc**/ 

object$token = RQ$RECEIVE$MESSAGE (mbx$token, 

wait$forever , 

^response, 

^status) ; 
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SET$INTERRUPT 


interrupt$handler 


interrupt$handler$ds 


• if unequal to zero, indicates that the calling 
task is to be the interrupt task that will be 
invoked by the interrupt handler being set. The 
priority of the calling task is adjusted by the 
Nucleus according to the interrupt level being 
serviced. Table 8-4 lists the levels and the 
corresponding interrupt task priorities. Be 
certain that priorities set in this manner do 
not violate the max$priority attribute of the 
containing job. 

The value of this parameter indicates the number of 
outstanding SIGNAL$ INTERRUPT requests that can 
exist. When this limit is reached, the associated 
interrupt level is disabled. The maximum value for 
this parameter is 255 decimal. Chapter 8 describes 
this feature in more detail. 

A POINTER to the first instruction of the interrupt 
handler. To obtain the proper start address for 
interrupt handlers written in PL/M-86 , place the 
following instruction before the call to 

SET$ INTERRUPT: 

interrupt$handler 

= interrupt$ptr (inter); 

where interrupt$ptr is a PL/M-86 built-in 

procedure and inter is the name of your 
interrupt handling procedure. 

A WORD which specifies the interrupt handler’s data 
segment. 

• If not zero, contains the base address of the 

interrupt handler’s data segment. See the 

description of ENTER$ INTERRUPT in this chapter 
for information concerning the significance of 
this parameter. 

It is often desirable for an interrupt handler 
to pass information to the interrupt task that 
it calls. The following PL/M-86 statements, when 
included in the interrupt task’s code (with the 
first statement listed here being the first 
statement in the task’s code), will extract the 
DS register value used by the interrupt task and 
make it available to the interrupt handler, 
which in turn can access it by calling 
ENTER$ INTERRUPT: 
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DECLARE BEGIN WORD; /* A DUMMY VARIABLE */ 
DECLARE DATA.$PTR POINTER; 

DECLARE DATA.$ADDRESS STRUCTURE ( 

OFFSET WORD, 

BASE WORD) AT (@DATA$PTR) ; /* THIS MAKES 

ACCESSIBLE THE TWO HALVES OF THE 
POINTER DATA$PTR */ 

DATA$PTR = eSEGIN; /* PUTS THE WHOLE 

ADDRESS OF THE DATA SEGMENT INTO 
DATA$PTR AND DATA$ADDRESS */ 

DS$BASE = DATA$ADDRESS . BASE ; 

CALL RQ$SET$ INTERRUPT ( . . . ,DS$BASE) ; 

• if zero, indiceites that the interrupt handler 
will load its own data segment and may not 
invoice ENTER$ INTERRUPT. 


OUTPUT PARAMETER 

except$ptr A POINTER to a WORD to which the iRMX 86 Operating 

System will return the condition code generated by 
this system call. 


DESCRIPTION 

The SET$INTERRUPT system call is used to inform the Nucleus that the 
specified interrupt handler is to service interrupts which come in at the 
specified level. In a call to SET$ INTERRUPT, a task must indicate 
whether the interrupt handler will invoice an interrupt task and whether 
the interrupt handler has its own data segment. If the handler is to 
invoke an interrupt task, the call to SET$INTERRUPT also specifies the 
number of outstanding SIGNAL$INTERRUPT requests that the handler can make 
before the associated interrupt level is disabled. This number generally 
corresponds to the number of buffers used by the handler and interrupt 
task. Refer to Chapter 8 for further information. 

If there is to be an interrupt task, the calling task is that interrupt 
task. If there is no interrupt task, SET$INTERRUPT also enables the 
specified level, which must be disabled at the time of the call. 
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A$ATTACH$FILE 


A$ATTACH$FILE creates a connection to an existing file. 


CALL RQ$A$ATTACH$FILE(user , prefix, subpath$ptr, resp$mbox, 

except$ptr) ; 


INPUT PARAMETERS 
user 


prefix 


subpath$ptr 


A TOKEN for the user object to be inspected in any 
access checking that takes place. A zero 
specifies the default user for the calling task’s 
job. This parameter is ignored when attaching 
physical or stream files. Access checking does 
occur for named files. 

A TOKEN for the connection object to be used as 
the path prefix. A zero specifies the default 
prefix for the calling task’s job. 

A POINTER to a STRING containing the subpath of 
the file to be attached. A null string indicates 
that the new connection is to the file designated 
by the prefix. The new connection will not be 
open, regardless of the open mode of the prefix. 
(This parameter is ignored for physical and stream 
files . ) 




OUTPUT PARAMETERS 

resp$mbox A TOKEN for the mailbox into which the Basic I/O 

System places a token for the result object of the 
call. This result object is a new file connection 
if the call succeeds or an I/O result segment 
otherwise (see Appendix C). To ascertain the type 
of object returned, use the Nucleus system call 
GET$TYPE. 

If the object received is an I/O result segment, 
the calling task should call DELETE$SEGMENT to 
delete the segment after examining it. 

except$ptr A POINTER to a WORD where the sequential condition 

code will be returned. 
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A$ATTACH$FILE 


DESCRIPTION 

A$ATTACH$FILE creates a connection to an existing file. Once the 
connection is established, it remains in effect until the connection 
object is deleted, or until the creating job is deleted. Once attached, 
the file may be opened, closed, read, written, etc., as many times as 
desired. A$ATTACH$FILE has no effect on the owner ID or the access list 
for the file. 


CONDITION CODES 

A$ATTACH$FILE returns condition codes at two different times. The code 
returned to the calling task immediately after invocation of the system 
call is considered a sequential condition code. A code returned as a 
result of asynchronous processing is a concurrent condition code. A 
complete explanation of sequential and concurrent parts of system calls 
is in Chapter 7 of this manual. 

The following list is divided into two parts — one for sequential codes, 
and one for concurrent codes. 


Sequential Condition Codes 

The Basic I/O System can return the following condition codes to the word 
specified by the except$ptr parameter of this system call. 

E$OK No exceptional conditions. 

E$DEV$OFF$LINE The prefix parameter in this system call refers to 

a logical connection. One of the following is true 
of the device associated with the connection: 

• It has been physically attached but is now 
off-line. 

• It has never been physically attached. (See 

Appendix E for a more detailed explanation.) 

E$EXIST One of the following is true: 

• One or more of the following parameters is not 
a token for an existing object: 

- The user parameter 

- The prefix parameter 

- The respimbox parameter 

• The prefix connection is being deleted. 
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E$LIMIT 


E$MEM 

E$NO$PREFIX 


E$NO$USER 


E$NOT$CONFIGURED 


Processing this call would cause one or more of 
these limits to be exceeded: 

• The object limit for this job. 

• The number of I/O operations that can be 
outstanding at one time for the user object 
specified in the call (255 decimal). 

• The number of I/O operations that can be 
outstanding at one time for the caller’s job 
(255 decimal). 

The memory available to the calling task’s job is 
not sufficient to complete the call. 

The calling task specified a default prefix 
(prefix argument equals zero), but no default 
prefix can be found because of one of the 
following reasons: 

• When this job was created, a size of zero was 
specified for its object directory, so the job 
cannot catalog a default prefix. 

• The job’s directory can have entries but a 

default prefix is not cataloged there. 

If the user parameter in this call is not zero , 
the parameter is not a token for a user object. 

If the user parameter is zero . it specifies a 

default user. But no default user can be found 
because of one of the following reasons: 

• When this job was created, a size of zero was 
specified for its object directory, so the job 
cannot catalog a default user. 

• The job’s directory can have entries but a 

default user is not cataloged there. 

• The object that is cataloged with the name 

R?IOUSER is not a user object. The name 
R?IOUSER should be treated as a reserved word. 

This system call is not part of the present 
conf igurat ion . 
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E$TYPE One of more of the following conditions caused 

this exception: 

• The prefix parameter is a token for an object 
that is not of the correct type. It must be 
either a connection object or a logical device 
object. (Logical device objects are created 
by the Extended I/O System.) 

• The resp$mbox parameter in the call is a token 
for an object that is not a mailbox. 


Concurrent Condition Codes 

The Basic I/O System can return the following condition codes in an I/O 
result segment at the mailbox specified by resp$mbox. After examining 
the segment, you should delete it. 

E$OK No exceptional conditions. 

E$DEV$DETATCHING The file specified is on a device that the system 

is detaching. 

E$FNEXIST A file in the specified path, or the target file 

itself, does not cixist or is marked for deletion. 

E$FTYPE The string pointed to by the subpath$ptr parameter 

contains a filename that should be the name of a 
directory, but is not. (Except for the last file, 
each file in a path must be a named directory.) 

E$INVALID$FNODE The fnode for the specified file is invalid. The 

file cannot be accessed; you should delete it. 

E$IO An I/O error occurred, which might have prevented 

the operation from completing. Examine the 
unit$status field of the I/O result segment for 
more information. 

E$IO$HEM The memory available to the Basic I/O System job 

is not sufficient to complete the call. 
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A$CHANGE$ACCESS 


A$CHANGE$ACCESS changes the access rights to a named data or directory 
file. 


CALL RQ$A$CHANGE$ACCESS(user, prefix * subpath$ptr, id» access, 

resp$mbox, except$ptr); 


INPUT PARAMETERS 

user A TOKEN for the user object to be inspected in 

access checking. A value of zero specifies the 
default user for the calling task’s job. 

prefix A TOKEN for the connection object to be used as 

the path prefix. A zero specifies the default 
prefix for the calling task’s job. 

subpath$ptr A POINTER to a STRING giving the subpath of the 

file whose access is to be changed. A null string 
indicates that the prefix itself designates the 
desired file. 

id A WORD containing the ID number of the user whose 

access is to be changed. If this ID does not 
already exist in the ID-access mask list, it is 
added. This list may contain a total of three 

ID-access pairs. 

access A BYTE mask giving the new access rights for the 

ID. For each bit, a one grants access, and a zero 
denies it. (Bit 0 is the low-order bit.) For a 
named data file, the possible bit settings are: 

Bit 
0 
1 
2 
3 

4-7 


Meaninx 

Delete 

Read 

Append 

Update 

Reserved (set to 0) 
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For a named directory 
settings are: 

Bit 

0 

1 

2 

3 

4-7 

If zero is specified 
(that is, no access), 
parameter is deleted 
list. 


file, the possible bit 


Meaning 

Delete 

Display 

Add Entry 

Change Entry 

Reserved (set to 0) 

for the access parameter 
the ID specified in the id 
from the file’s ID-access 


OUTPUT PARAMETERS 

resp$mbox A TOKEN for the mailbox that receives an I/O 

result segment indicating the result of the call 
(see Appendix C) . A value of zero means that you 
do not want to receive an I/O result segment. 

If it receives an I/O result segment, the calling 
task should call DELETE$ SEGMENT to delete the 
segment after examining it. 

except$ptr A POINTER to a WORD where the sequential condition 

code will be returned. 


DESCRIPTION 

A$CHANGE$ACCESS system call applies to named files only. This call has 
no effect on existing connections to the file. It is called to change 
the access rights to a named data or directory file. Depending on the 
contents of the ”id” and ’’access” parameters specified in the system 
call, users may be added to or deleted from the file’s ID-access mask 
list, or the access privileges granted to a particular user may be 
changed . 


NOTE 

The caller must be the owner of the 
file or must have change entry access 
to the file’s parent directory. 
However, if the owner is ’’WORLD”, that 
is, 0FFFFH, then any task may change 
the access mask of the file. 
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granularity 


size 

must$create 


OUTPUT PARAMETERS 
resp$mbox 


except$ptr 

REPLACE 
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A WORD giving the granularity of the file being 
created. This is the size (in bytes) of each 
logical block to be allocated to the file. The 
value specified in this parameter is rounded up, 
if necessary, to a multiple of the volume 
granularity. Note that a contiguous file can 
become noncontiguous when it is extended. 

The granularity parameter can have the following 
values: 

0 Same as volume granularity 

FFFF The file must be contiguous 

Other Number of bytes per allocation 

When a contiguous file is extended, space is 
allocated in volume-granularity units. If ’’Other” 
is specified, a multiple of 1024 bytes is 

recommended . 

This parameter is ignored for physical and stream 
files . 

A DWORD giving the number of bytes initially 
reserved for the file. For stream files, this 
value must equal zero. For physical files, this 
parameter is ignored. 

A BYTE whose value (0FFH for TRUE or 0 for FALSE) 
determines the handling of input paths designating 
an existing file (see following DESCRIPTION). 
This parameter applies only to named files. 


A TOKEN for the mailbox that receives the result 
object of this call. This result object is a new 
file connection if the call succeeded or an I/O 
result segment otherwise (see Appendix C). To 
ascertain the type of object returned, use the 
Nucleus system call GET$TYPE. 

If the object received is an I/O result segment, 
the calling task should call DELETE$ SEGMENT to 
delete the segment after examining it. 

A POINTER to a WORD where the sequential condition 
code will be returned. 
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DESCRIPTION 

The A$CRBATE$FILE system call creates a physical, stream, or named data 
file and returns a token for the new file connection. If a named file 
designated by the prefix and subpath parameters already exists, one of 
the following occurs: 

• Error : If the ”must$create*’ parameter is TRUE (0FFH) , an error 

condition code (E$FEXIST) is returned. 

• Truncate File: If the "mustlcreate” parameter is FALSE (0) and 

the path designates an existing data file, a new connection to 
that file is returned (that is, A$CREATE$FILE acts like 
A$ATTACH$FILE) . In this case, the file is truncated or expanded 
according to the ’’size” parameter, so data in the file might be 
lost. As in the case of A$ATTACH$FILE, the file’s owner ID and 
access list are unchanged. 

• Temporary File Created: If the ”must$create” parameter is FALSE 

(0), and the path designates an existing directory file or 
device, an unnamed temporary file is created on the corresponding 
device. This file is deleted automatically when the last 
connection to it is deleted. Because this file is created 
without a path, it can be accessed only through a connection. 

Any task can create a temporary file by referring to any 
directory. This is true because temporary files are not listed 
as ordinary entries in the directory, so no add-entry access is 
required . 

Many of the parameters specified in the A$CREATE$FILE call do not apply 
to physical and stream files. In these cases, the parameter is ignored. 


NOTE 

The caller must have add-entry access 
to the parent directory of the new 
named file. 


CONDITION CODES 

A$CREATE$FILE returns condition codes at two different times. The code 
returned to the calling task immediately after invocation of the system 
call is considered a sequential condition code. A code returned as a 
result of asynchronous processing is a concurrent exception code. A 
complete explanation of sequential and concurrent parts of system calls is 
in Chapter 7 of this manual. 

The following list is divided into two parts -- one for sequential codes, 
and one for concurrent codes. 
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A$SPECIAL 

A$SPECIAL enables tasks to perform a variety of special functions. 


CALL RQ$A$SPECIAL( connection, spec$func, ioparm$ptr, resp$mbox, 

except$ptr) ; 


INPUT PARAMETERS 

connection A TOKEN for a connection to the file or device for 

which the special function is to be performed. 

spec$func An encoded WORD that, with the connection argument. 


specifies the 

function being 

requested. The 

functions are 

described under the heading 

DESCRIPTION and 

are summarized as 

follows: 

File driver 

Spec$func 


for connection value 

Function 

Physical 

0 

Format track 

Stream 

0 

Query 

Stream 

1 

Satisfy 

Physical or Named 2 

Notify 

Physical 

3 

Get disk/tape 
data 

Physical 

4 

Get terminal data 

Physical 

5 

Set terminal data 

Physical 

6 

Set signal 

Physical 

7 

Rewind tape 

Physical 

8 

Read tape file 
mark 

Physical 

9 

Write tape file 
mark 

Physical 

10 

Retention tape 


11-32767 

Reserved for 
other Intel 
products 


ioparm$ptr A POINTER to a parameter block. The contents of 

the parameter block depends upon the requirements 
of the special function being requested and are 
described fully under the heading DESCRIPTION. 
Enter a zero value if the special function you 
request does not require a parameter block. 
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A$SPECIAL 


OUTPUT PARAMETERS 

resp$mbox A TOKEN for the mailbox that receives an I/O result 

segment indicating the result of the call (see 
Appendix C) . A value of zero means that you do not 
want to receive an I/O result segment. 

If it receives an I/O result segment, the calling 
task should call DELETE$ SEGMENT to delete the 
segment . 

except$ptr A POINTER to a WORD where the sequential condition 

code will be returned. 


DESCRIPTION 

The A$SPECIAL system call enables tasks to perform a variety of special 
functions . 

Tasks define their requests by means of the spec$func and ioparm$ptr 
parameters. Spec$func is a code which, when combined with the file 
driver associated with the connection argument, specifies the function 
the Basic I/O System is to perform. Wlien more information is needed to 
define a request, ioparm$ptr points to a parameter block containing the 
additional data. Descriptions of the available functions follow. 


Formatting a Track. This function applies to physical files only. To 
format a track on a mass storage device, call A$SPEGIAL with an open file 
connection, with spec$func equal to 0, and with ioparm$ptr pointing to a 
structure of the form: 


DECLARE format$ track STRUCTURE ( 


track$number WORD , 

interleave WORD, 

track$offset WORD, 

f illlchar WORD) ; 


In this structure, the fields are defined as follows: 

track$number The number of the track to be formatted. 

Acceptable values are 0 to one less than the 
number of tracks on the volume. Other values 
cause an E$SPACE exceptional condition. When 
formatting a RAM-disk or a tape, you must place a 
zero value in this field. 


interleave The interleave factor for the track. (That is, 

the number of physical sectors to advance when 
locating the next logical sector.) An interleave 
factor of zero or one skips no physical sectors 
between logical sectors. If the specified 
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Bits Value and Meaning 

2 Output medium (corresponds to OSC 

characters T:H). 

0 = Video display terminal (VDT) . 

1 = Printed (Hard copy) . 

3 Modem indicator (corresponds to OSC 

characters T:M). 

0 = Not used with a modem. 

1 = Used with a modem. 

4-5 Input parity control (corresponds to OSC 
characters T;R). The parity bit (bit 7) 
of each input byte can be used in a 
variety of ways. A byte has even parity 
if the sum of its bits is an even 

number. Otherwise, the byte has odd 

parity. 

0 = Always set parity bit to 0. 

1 = Never alter the parity bit. 

2 = Even parity is expected on input. 

Use the parity bit to indicate the 
presence (1) or absence (0) of an 

error on input. That is, set the 

parity bit to 0 unless the received 
byte has odd parity or there is some 
other error, such as (a) the received 
stop bit has a value of 0 (framing 

error) or (b) the previous character 
received has not yet been fully 

processed (overrun error.) 

3 = Odd parity is expected in input. Use 

the parity bit to indicate the 
presence (1) or absence (0) of an 

error on input. That is, set the 

parity bit to 0 unless the received 
byte has even parity or there is some 
other error, such as (a) the received 
stop bit has a value of 0 (framing 

error) or (b) the previous character 
received has not yet been fully 

processed (overrun error.) 
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Bits Value and Meaning 

6-8 Output parity control (corresponds to OSC 
characters T:W). The parity bit (bit 7) 
of each output byte can be used in a 
variety of ways. A byte has even parity 
if the sum of its bits is an even 
number. Otherwise, the byte has odd 
parity. 

0 = Always set parity bit to 0. 

1 = Always set parity bit to 1. 

2 = Set parity bit to give the byte even 

parity. 

3 = Set parity bit to give the byte odd 

parity. 

4-7 = Do not alter parity bit. 

9 Translation control (corresponds to OSC 

characters T;T). Translation refers to 
the ability to define certain control 
characters so that whenever these 

characters are entered at or written to a 
terminal, certain actions, usually cursor 
movements, take place automatically. 
Translation is described in Appendix F of 
this manual. 

0 = Do not enable translation. 

1 = Enable translation. 

10 Terminal axes sequence control 

(corresponds to OSC characters T:F). 

This specifies the order in which 

Cartesian- like coordinates of elements on 
a terminal's screen are to be listed or 
entered . 

0 = List or enter the horizontal 

coordinate first. 

1 = List or enter the vertical coordinate 

first. 

11 Horizontal axis orientation control 

(corresponds to OSC characters T:F). 

This specifies whether the coordinates on 
the terminal's horizontal axis increase 
or decrc^ase as you move from left to 
right across the screen. 
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in$baud$rate 


out$baud$rate 


Bits Value and Meaning 


0 = Coordinates 
right . 

increase 

from 

left 

to 

1 = Coordinates 
right . 

decrease 

from 

left 

to 


12 Vertical axis orientation control 
(corresponds to OSC characters T:F). 
This specifies whether the coordinates on 
the terminal’s vertical axis increase or 
decrease as you move from top to bottom 
across the screen. 


0 = Coordinates 
bottom. 

increase 

from 

top 

to 

1 = Coordinates 
bottom. 

decrease 

from 

top 

to 


13-15 Reserved bits. For future compatibility, 
set to 0. 


NOTE 

If bits 4-5 contain 2 or 3, and bits 
6-8 also contain 2 or 3, then they must 
both contain the same value. That is, 
they must both reflect the same parity 
convention (even or odd). 


The input baud rate indicator (corresponds to OSC 
characters T:I). If you attempt to set this field 
to zero, the Basic I/O System ignores your entry 
and leaves the field set to its previous value. 
The word is encoded as follows: 

0 = Invalid. 

1 Perform an automatic baud rate search. 

Other = Actual input baud rate, such as 9600. 

The output baud rate indicator (corresponds to OSC 
characters T:0). If you attempt to set this field 
to zero, the Basic I/O System ignores your entry 
and leaves the field set to its previous value. 
The word is encoded as follows: 

0 = Leave field set to previous value 

1 = Use the input baud rate for output. 
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Other = Actual output baud rate, such as 9600. 

Most applications require the input and output 
baud rates to be equal. In such cases, use 
in$baud$rate to set the baud rate and specify a 
one for out$baud$rate. 

scroll$lines An operator at a terminal can enter a control 

character (default is Control-W) when he/ she is 
ready for data to appear on the terminal’s display 
screen. The scroll$lines value (corresponding to 
OSC characters T:S) specifies the maximum number 
of lines that are to be sent to the terminal each 
time the operator enters the control character. 
If you attempt to set this 

field to zero, the Basic I/O System ignores your 
entry and leaves the field set to its previous 

value. 

x$y$size The low-order byte of this word specifies the 

number of character positions on each line of the 
terminal’s screen (and corresponds to OSC 
characters T:X). The high-order byte specifies 
the number of lines on the terminal’s screen (and 
corresponds to OSC characters T:Y). 

x$y$offset The low-order byte of this word specifies the 

value that starts the numbering sequence of both 
the X and Y axes (and corresponds to OSC 

characters T:U). The high-order byte specifies 
the value to which the numbering of the axes must 
"fall back" after reaching 127 (and corresponds to 
OSC characters T:V). 

The remaining fields apply only for intelligent communications boards 
(such as the iSBC 544 board) that maintain their own input and output 
buffers separately from the ones managed by the Basic I/O System’s 

Terminal Support Code. If you aren’t sure whether you can set these 
fields, invoke A$SPECIAL with function code 4 to get the terminal 

attributes. If bit 15 of the flow$control field (the next one described) 
is set, your board is a buffered device and you can set the following 
fields. (If your board is not a buffered device, setting any of the 

following fields will cause the terminal support code to return an 
E$PARAM Condition Code.) 

flow$control Specifies whether the communications board sends 

flow control characters (selected by the 
fc$on$char and fc$off$char fields, but usually XON 
and XOFF) to turn input on and off (corresponds to 
the OSC characters T:G). The low-order bit (bit 

0) controls this option, as follows: 

0 Disable flow control. 

1 Enable flow control. 
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DELCLARE read$f ile$mark STRUCTURE ( 

search BYTE) ; 

Where: 

search A value indicating the direction of the search, as 

follows: 

00 Search forward 

0FFH Search backward (for start/stop drives 
only) 

When your task issues the A$SPECIAL system call with spec$func set to 9, 
the tape drive writes a file mark at the current position on the tape. 
This function also terminates tape write operations. 

When your task issues the A$SPECIAL system call with spec$func set to 10, 
the tape drive fast-forwards the tape to the end and then rewinds it to 
the load point. 


CONDITION CODES 

A$SPEC1AL return condition codes at two different times. The code 
returned to the calling task immediately after invocation of the system 
call is considered a sequential condition code. A code returned as a 
result of asynchronous processing is a concurrent condition code. A 
complete explanation of sequential and concurrent parts of system calls 
is in Chapter 7 of this manual. 

The following list is divided into two parts — one for sequential codes, 
and one for concurrent codes. 


Sequential Condition Codes 

The Basic I/O System can return the following condition codes to the word 
specified by the except$ptr parameter of this system call. 

E$OK No exceptional conditions. 

E$BUFFERED$CONN The connection parameter is a connection produced 

by the Extended I/O System. You cannot use it 
with Basic I/O System calls. 

E$EXIST At least one of the following is true: 

• One or more of the following parameters or 
fields is not a token for an existing object: 
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E$IFDR 

E$LIMIT 

E$HEH 

E$NOT$CONFIGURED 

E$PARAM 


E$ SUPPORT 


- The connection parameter 

- The resp$mbox parameter 

- The mailbox field in the notify structure. 
(Spec$func » 2.) 

- The object field in the notify structure. 
(Spec$func s* 2.) 

- The semaphore field in the signal$pair 
structure. (Spec$func =6.) 

• The connection is being deleted. 

The function requested (spec$func) is not valid 
for the type of file specified by the connection 
parameter . 

The calling task’s job has already reached its 
object limit. 

The memory available to the calling task’s job is 
not sufficient to complete the call. 

This system call is not part of the present 
configuration. 

At least one of the following is true: 

• The spec$func parameter was 6 , and the 
character field was greater than IFH. 

• The spec$func parameter was greater than 10. 

• One or more of the fields related to buffered 
devices (high$water$mark, low$water$mark, 
fc$on$char, fc$off$char) was set while bit 15 
of the flow$control field was reset to zero 
(specifying an unbuffered device). 

The specified connection was not created by this 
job. 
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E$TYPE One or more of the following parameters or fields 

is a token for an existing object of the wrong 
type: 

• The connection parameter. 

• The resp$mbox parameter. 

• The mailbox field of the notify structure. 
(Spec$func =2.) 

• The semaphore field of the signal$pair 

structure. (Spec$func =6.) 


Concurrent Condition Codes 

The Basic I/O System can return the following condition codes in an I/O 
result segment at the mailbox specified by resp$mbox. After examining 
the segment, you should delete it. 

E$OK No exceptional conditions. 

E$CONN$NOT$OPEN The specified connection is not open. This 

applies only to stream and physical files. 

E$FLUSHING The specified connection was closed before the 

function could be completed. 

E$IDDR The specified function is not supported by the 

device containing the file. 

E$IO An I/O error occurred which might have prevented 

the operation from completing. Examine the 
unit$status field of the I/O result segment for 
more information. 

E$NOT$DEVICE$CONN The function code is * notify' , but the specified 

connection is not a device connection. This 
applies only to named and physical files. 

E$PARAM The spec$func parameter was 5 while bits 0-1 of 

the connect ion$f lags field was equal to 0. 

eIspaCE One of the following is true: 

• This call attempted to format a track of a 
physical file that is beyond the end of the 
volume. 

• This call attcimpted to format a track of a RAM 
disk other than track 0. 
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E$STREAM$SPECIAL 


One of the following is true: 

• This is a "query” request, but another query is 
already queued. This applies only to stream 
files. 

• This is a "satisfy” request, but either a query 
request is queued, or no requests are queued. 
This applies only to stream files. (See 
Artificially Satisfying a Stream File I/O 
Request in the DESCRIPTION . ) 
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E$TYPE At least one of the following is true: 

• The connection parameter is a token for an 
object that is not a connection. 

• The resp$mbox parameter is a token for an 
object that is not a mailbox. 


Concurrent Condition Codes 

The Basic I/O System can return the following condition codes in an I/O 
result segment at the mailbox specified by resp$mbox. After examining 
the segment, you should delete it. 

E$OK No exceptional conditions. 

E$CONN$NOT$OPEN The specified file is not open for writing or 

updating. 

E$IO An I/O error occurred which might have prevented 

the operation from completing. Examine the 
unit$status field of the I/O result segment for 
more information. 
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A$UPDATE 


A$UPDATE updates a device by writing all partial sectors that remain in 
the Basic I/O System's buffers after the most recent A$WRITE call. 


CALL RQ$A$UPDATE( connect ion, resp$mbox, except$ptr) ; 


INPUT PARAMETERS 

connection A TOKEN for a file or device connection. A$UPDATE 

updates all files on the device. 

resp$mbox A TOKEN for the mailbox that receives an I/O 

result segment indicating the result of the call 
(see Appendix C) . A value of zero means that you 
do not want to receive an I/O result segment. 

If it receives an I/O result segment, the calling 
task should call DELETE$SEGMENT to delete the 
segment after examining it. 


OUTPUT PARAMETER 

except$ptr A POINTER to a WORD where the sequential condition 

code will be returned. 


DESCRIPTION 

When the I/O System performs an A$WRITE operation, it writes only entire 
sectors. If part of a sector remains to be written, the I/O System, 
unless requested to finish the writing operation (that is, to "update the 
file"), leaves the data for a partial sector in an output buffer. The 
next time A$WRITE is called on behalf of that file, the I/O System 
combines the leftover data in the buffer with the data in the new request 
and again begins writing entire sectors. 

The A$UPDATE system call forces the Basic I/O System to finish the 
writing operation for a device; that is, it writes all partial buffers 
pertaining to files on a particular device. This ensures that files on 
removable volumes (such as diskettes) are updated before the operator 
removes the volume. However, the A$UPDATE system call has no effect on 
buffers that the Extended I/O System manages. 


REPLACE 


BIOS 8-110 


UPDATE 3, 3/85 


INSPECT$USER 


CONDITION CODES 
E$OK 
E$EXIST 

E$NOT$CONFIGURED 

E$PARAM 

E$TYPE 


No exceptional conditions. 

The user parameter is not a token for an existing 
ob j ect . 

This system call is not part of the present 
configuration. 

The length field contains a zero value. 

The user parameter is a token for an object of the 
wrong type. 
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SET$DEFAULT$PREFIX 


SET$DEFAULT$PREFIX sets the default prefix for an existing job. 


CALL RQ$SET$DEFAULT$PREFIX(job, prefix, except$ptr) ; 


INPUT PARAMETERS 

job A TOKEN for the job whose default prefix is to be 

set. A zero specifies the current job. 

prefix A TOKEN for the connection that is to become the 

default prefix. 


OUTPUT PARAMETERS 

except$ptr A POINTER to a WORD where the condition code will 

be returned. 


DESCRIPTION 

The SET$DEFAULT$PREFIX system call sets the default prefix for an 
existing job. It does this by cataloging, the connection (supplied as the 
prefix parameter) in the object directory of the job (supplied as the job 
parameter). The Basic I/O System catalogs the prefix under the name 
If an object is already cataloged under the name the Basic I/O 

System uncatalogs that object before cataloging the new prefix. 


CONDITION CODES 

E$OK No exceptional conditions. 

E$CONTEXT When this job was created, a size of zero was 

specified for the object directory, so a default 
prefix cannot be cataloged 

E$EXIST One or more of the following parameters is not a 

token for an existing object: 

• The job parameter 

• The prefix parameter 
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create a segment every time an I/O result segment is needed. This 
provides a significant advantage because A$READ, A$WRITE, and A$SEEK are 
typically the most commonly invoked Basic I/O System calls. 


CONDITION CODES 

E$OK No exceptional conditions. 

E$EXIST At least one of the following is true: 

• The connection parameter or the resp$mbox 

parameter (or both) did not contain a token 

for an existing object. 

• The specified connection or response mailbox 

(or both) was deleted. 

• The token returned to the specified mailbox 
was for an object that had been deleted. 

E$IO$HARD A hard I/O error occurred. Another retry is 

probably useless. 

E$IO$HODE At least one of the following is true: 

• A tape drive attempted to perform a read 

operation before the previous write operation 
completed. 

• A tape drive attempted to perform a write 
operation before the previous read operation 
completed. 

E$IO$NO$DATA A tape drive attempted to read the next record, 

but it found no data. 

E$IO$OPRINT The device was off-line. Operator intervention is 

required. 

E$IO$SOFT A soft I/O error occurred. The Basic I/O System 

tried to perform the operation a number of times 
(the number is configurable for each device). All 
attempts failed. If the configurable value 
specifying the number of retries is a reasonable 
value (for example, 9), another retry probably 
won’t be successful either. 

E$IO$UNCLASS An unknown type of I/O error occurred. 

E$IO$WRPROT The asynchronous operation was A$WRITE and the 

volume was write-protected. 

E$N0T$C0NFI6URED This system call is not part of the present 

configuration. 
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E$TIME One of the following is true: 

• The calling taisk was not willing to wait, and 

there was no I/O result segment at the 
specified mailbox. 

• The specified waiting period elapsed before 

the response mailbox received an I/O result 
segment . 

E$TYPE At least one of the following is true: 

• The connection parameter is a token for an 

object that is not a file connection. 

• The resp$mbox parameter is a token for an 

object that is not a mailbox. 

• The object received at the response mailbox is 

not a segment or is a segment that is not an 

I/O result segment. 
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start$address 


data$seg 


stackiptr 


stack$size 


• If equal to zero, specifies that the new job’s 
initial task is to have a priority equal to the the 
maximum priority of the initial job of the Extended 
I/O System. For more information about the initial 
job of the Extended I/O System, refer to the 
chapter of the iRMX CONFIGURATION GUIDE relating to 
the Extended I/O System. 

• If not equal to zero, contains the priority of the 
initial task of the new job. If this priority is 
higher than (numerically less than) the maximum 
priority of the initial job of the Extended I/O 
System, an E$PARA1<[ error occurs. 

A POINTER to the first instruction of the code 
segment for the new job’s initial task. This code 
segment can be, but is not required to be, an iRMX 86 
segment. 

A WORD which, 

• if zero, indicates one of two things. Either the 
new job’s initial task uses no data segment, or it 
creates one for itself. Tasks can create their own 
data segments only under special circumstances. To 
find out more about the circumstances, refer to the 
iRMX 86 CONFIGURATION GUIDE. 

• if not zero, contains the base address of the data 
segment of the new job’s initial task. This data 
segment can be, but is not required to be, an 
iRMX 86 segment. 

A POINTER which, 

• if the base portion is zero, specifies that the 
Nucleus should allocate a stack for the new job’s 
initial task. The length of the allocated stack is 
determined by the stack$size parameter of this 
system call. Be aware that this stack is not an 
iRMX 86 segment. 

• if the base portion is not equal to zero, points to 

the base of the stack for the new job’s initial 
task. Because the Nucleus does not allocate this 
stack, you must allocate it during the 

configuration process, or your application code 
must allocate it while the system is running. 

A WORD containing the size, in bytes, of the stack 
for the new job’s initial task. If you specify less 
than 200, the Extended I/O System will increase the 
size to 200. For information regarding the amount of 
stack to allocate, refer to the chapter of the 
iRMX 86 PROGRAMMING TECHNIQUES manual that discusses 
stack sizes. 
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task$f lags 


msg$mbox 


If you are allocating the stack during configuration, 
or if the application code is allocating the stack 
while the system is running, the value of this 
parameter will be the precise amount of stack that 
the system can use. However, if the Nucleus is 
allocating the stack for you, it might allocate as 
many as 15 additional bytes in order to make the 
stack occupy whole 16 -byte paragraphs. 

A WORD in which all bits except the two low-order 
bits are set to zero. 

Bit Zero ; Use the low-order bit (bit 0) to tell the 
Operating System whether the new job’s initial task 
uses floating-point instructions. A value of 1 
indicates the presence of floating-point 
instructions, while a zero indicates the absence of 
floating-point instructions. 

Bit One : Bit 1 indicates whether the initial task in 

the job should run immediately, or whether it should 
wait until a START$IO$JOB system call is issued to 
start it. Set bit 1 to zero if the task is to be 
made ready to run; set bit 1 to one if the task is to 
wait until the START$IO$JOB call is issued. 

A TOKEN for a mailbox. When a task exits (by 

invoking EXIT$IO$JOB) , the Extended I/O System sends 
a message to this mailbox. If you desire no such 
message, assign msg$mbox a value of zero. 

The format of the message is as follows: 

DECLARE message STRUCTURE ( 
terminal ion$code WORD, 
user$fault$code WORD, 

job$token WORD, 

retum$data$'Len BYTE, 

retum$data(^0 BYTE) 


A WORD that indicates why an I/O 
job terminated, as follows: 


MEANING 

Some task within the job — the terminating 
task — invoked the EXIT$IO$JOB system call, 
and indicated with this code that no problem 
caused the termination. The job has not yet 
been deleted, and some of its tasks might still 
be ready. 


where : 

termina- 

tion$code 

CODE 

0 
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The iRMX 86 Extended I/O System uses condition codes to inform your tasks 
of any problems that occur during the execution of a system call. If no 
problems occur and the system call runs to completion, the Extended I/O 
System returns an E$OK condition code. Otherwise, the Extended I/O 
System returns an exceptional condition code. 

The meaning of a specific exceptional condition code depends upon the 
system call that returns the code. For this reason, this appendix does 
not list any interpretations. 

This appendix provides you with the numeric value associated with each 
condition code that the Extended I/O System can return. To use the 
exception code values in a s 3 rmbolic manner, you can assign (using the 
PL/M-86 "literally” statement) a meaningful name to each of the codes. 

The following list correlates the name of the condition code (as 
described in Chapter 7 of this manual) to the value that the Extended I/O 
System actually returns. The list is divided into three parts; one for 
the normal condition code, one for tixception codes that indicate a 
programming error, and one for exception codes that indicate an 
environmental condition. 


NORMAL CONDITION CODE 

NAME OF CONDITION DECIMAL HEXADECIMAL 

E$OK 0 0H 


PROGRAMMING ERRORS 


NAME OF CONDITION 

DECIMAL 

HEXADECIMAL 

E$ZERO$DIVIDE 

32768 

8000H 

E$OVERFLOW 

32769 

8001H 

E$TYPE 

32770 

8002H 

ElPARAM 

32772 

8004H 

E$NOT$ SUPPORTED 

32773 

8005H 

E$NOUSER 

32801 

8021H 

E$NO$PREFIX 

32802 

8022H 

E$NOT$LOG$NAME 

32832 

8040H 

E$NOT$DEVICE 

32833 

8041H 

E$NOT$CONNECTION 

32834 

8042H 
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C0NDIT1019 CODES 


ENVIRONMENTAL CONDITIONS 

NAME OF CONDITION 

ElTIME 

E$MEM 

ElLIMIT 

E$CONTEXT 

E$EXIST 

E$NOT$CONFIGURED 

E$FEXIST 

E$FNEXIST 

E$DEVFD 

E$SUPPORT 

E$FACCESS 

ElFTYPE 

E$ SHARE 

E$SPACE 

E$IDDR 

ElFLUSHING 

E$ILLVOL 

ElIFDR 

E$FRAGMENTATION 

E$DIR$NOT$EMPTY 

E$NOT$FILE$CONN 

E$CONN$NOT$OPEN 

E$CONN$OPEN 

E$ALREADY$ATTACHED 

E$DEV$DETACHING 

E$NOT$SAME$DEV 

E$ILLOGICAL$RENAME 

E$STREAM$SPECIAL 

E$INVALID$FNODE 

E$PATHNAME$SYNTAX 

E$FNODE$LIMIT 

E$LOG$NAME$SYNTAX 

E$IOMEM 

E$MEDIA 

E$LOG$NAME$NEXIST 

E$NOT$OWNER 

E$IO$JOB 

E$IO$UNCLASS 

E$IO$SOFT 

E$IO$HARD 

E$IO$OPRINT 

E$IO$WRPROT 

E$IO$NO$DATA 

E$IO$MODE 


DECIMAL HEXADECIMAL 


1 

IH 

2 

2H 

4 

4H 

5 

5H 

6 

6H 

8 

8H 

32 

20H 

33 

21H 

34 

22H 

35 

23H 

38 

26H 

39 

27H 

40 

28H 

41 

29H 

42 

2AH 

44 

2CH 

45 

2DH 

47 

2FH 

48 

30H 

49 

31H 

50 

32H 

52 

34H 

53 

35H 

56 

38H 

57 

39H 

58 

3AH 

59 

3BH 

60 

3CH 

61 

3DH 

62 

3EH 

63 

3FH 

64 

40H 

66 

42H 

68 

44H 

69 

45H 

70 

46H 

71 

47H 

80 

50H 

81 

51H 

82 

52H 

83 

53H 

84 

54H 

85 

55H 

86 

56H 


I 
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local object directory 3-8 
logical device object 7-19, B-1 
logical names 3-7, 7-105 

devices 2-6, 3-4, 7-18, 7-20 
deletion of 7-105 
files 2-6, 4-5, 4-16 

LOGICAL$ATTACH$DEVICE system call 3-4, 4-14, 7-18 , 7-43 
LOGICAL$DETACH$DEVICE system call 4-14, 7-19, 7-20 

magnetic tape drive 7-99 
mailbox 7-9 

marking files for deletion 7-48 
maximum buffer size 2-6, 8-1 
maximum number of buffers 2-6 
memory pool 7-5 

memory requirements of I/O systems 1-3 
modem 7-93 

multiple connection to same file 3-5 
multiple files on same device 4-1 

named files 2-2, 4-1 
null string, pathname 3-9, 4-5 
number of buffers 2-5, 7-53, 7-66 
number of bytes read 7-70 
number of bytes vrritten 7-108 

object directories 3-7, 7-108, D-1 

objects, types B-1 

odd parity 7-93 

OFFSET data type A-1 

opening files 2-3, 7-53 

Operating System Control sequences (OSC) 7-92 
order of search for logical names 3-7 
overlapped I/O operations 1-2, 2-5 
owner ID 4-10 

parent directory 7-37, 7-75 

parity control, terminals 7-91 

path$ptr 3-9, 4-5, 7-37, 7-41, 7-48, 7-56, 7-74 

performance of I/O systems 1-3 

physical device 7-19 

physical files 2-2, 5-1 

POINTER data type A-1 

pool, memory 7-5 

prefixes 4-4 

protocol: stream files 6-1 

R? 10 JOB D-1 
R?I0USER 3-9, 4-8 
R?MESSAGE D-1 
RAM disk 7-84 

random access memory (RAM) B-1 
random I/O 1-4 
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re-attachment of devices 2-7 
Read (access control) 4-9, 7-29 
reading beyond end-of-file 7-79 
renaming directories 7-74 
renaming files 4-15, 7-74 
root named file directory 4-2 
root object directory 3-8 

RQ6L0BAL D-1, see also: global object directory 

S$ATTACH$FILE system call 4-3, 4-11, 4-13, 7-23 . 7-41 
S$CATALOG$CONNECTION system call 4-16, 7 -26 
S$CHANGE$ACCESS system call 4-4, 4-10, 4-12, 7-29 
S$CLOSE system call 4-3, 4-14, 7-34 
S$CREATE$DIRECTORY system call 4-4, 4-11, 4-13, 7-37 
S$CREATE$FILE system call 4-4, 4-11, 4-13, 7-41 
S$DELETE$CONNECTION system call 4-3, 4-13, 7-46 
S$DELETE$FILE system call 4-4, 4-15, 7-4 8 
S$GET$CONNECTION$STATUS system call 4-3, 7-52 
S$GET$FILE$STATUS system call 4-4, 7-56 
S$LOOK$UP$CONNECTION system call 4-16, 7-64 
S$OPEN system call 3-5, 4-3, 4-14, 7-66 
S$READ$MOVE system call 4-3, 4-14, 7-70 
S$RENAME$FILE system call 4-4, 4-15, 7-7 4 
S$SEEK system call 4-3, 4-14, 7-78 . 7-108 
S$SPECIAL system call 4-3, 4-16, 7-82 
S$TRUNCATE$FILE system call 4-3, 4-14, 7-41, 7-102 
S$UNCATALOG$CONNECTION system call 4-16, 7-105 
S$WRITE$MOVE system call 4-3, 4-15, 7-10 7 
satisfying stream files 7-87 
scrolling 7-96 
SELECTOR data type 7-1, A-1 
semaphore 7-98 

sequence of named file calls 4-18 
sequential I/O 2-6 

setting terminal characteristics 7-89 
signal characters at terminal 7-98 
special users 4-12 
stack 7-7 

start address for I/O job 7-7 
START$IO$JOB system call 4-17, 7-22 
status, connection 7-52 
status, file 7-56 
status, obtaining of 4-15, 7-14 
stream files 2-3, 6-1 . 7-84 
satisfaction 7-87 
STRING data type A-1 
subpath 4-4 

synchronous I/O system calls 1-2 
syntax (path) 4-5 
system calls 7-1 

asynchronous 1-2 
Basic I/O System 4-17 
dictionary 7-2 
Nucleus 4-17 
synchronous 1-2 
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A$LOAD 


CONDITION CODES 

The A$LOAD system call can return condition codes at two different 
times. Codes returned to the calling task immediately after invocation 
of the system call are sequential condition codes. Codes returned after 
the concurrent part of the system call has finished running are 
concurrent condition codes. The following list is divided into two parts 
— one for sequential codes and one for concurrent codes: 


Sequential Condition Codes 

The Loader can return any of the following condition codes to the WORD 
pointed to by the except$ptr parameter of this system call. 

E$OK No exceptional conditions. 

E$BAD$HEADER The target file does not begin with a valid header 

record for a loadable object module. Possibly the 
file is a directory. 

E$CHECKSUH The header record of the target file contains a 

checksum error. 

E$CONN$NOT$OPEN The Loader opened the connection but some other 

task closed the connection before the loading 
operation was begun. 

E$CONN$OPEN The calling task specified a connection that was 

already open. 

E$EXIST At least one of the following is true: 

• The connection parameter is not a token for an 
existing object. 

• The msg$mbox parameter did not refer to an 

existing object. 

• The mailbox specified in the response$mbox 

parameter was deleted before the loading 
operation was completed. 

E$FACCESS The specified connection did not have **read” access 

to the file. 

E$FLUSHING The device containing the target file is being 

detached . 

E$IO$HARD A hard I/O error occurred. This means that another 

try is probably useless. 

E$I0$0PR1NT The device containing the target file was 

off-line. Operator intervention is required. 
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E$IO$SOFT A soft I/O error occurred. This means that the I/O 

System tried to perform the operation and failed, 
but another try mijjht still be successful. 

E$IO$UNCLASS An unknown type of I/O error occurred. 


E$IO$WRPROT The volume is write-protected. 

E$LIMIT At least one of the following is true: 


• The calling task’s job has already reached its 
object limit. 

• Either the calling task’s job, or the job’s 
default user object, is already involved in 255 
(decimal) I/O operations. 

E$LOADER$ SUPPORT To load the target file requires capabilities not 

configured into the Loader. For example, it might 
be attempting to load PIC when configured to load 
only absolute code. 

E$MEM The memory available to the calling task’s job or 

the Basic I/O System is not sufficient to complete 
the call. 


E$NOT$FILE$CONN The calling task specified a connection to a device 

rather than to a named file. 


E$SHARE The calling task tried to open a connection to a 

file already being used by some other task, and the 
file’s sharing attribute is not compatible with the 
open request. 

E$SUPPORT The specified connection was not created by the 

calling task’s job.. 

E$TYPE The connection parameter is a token for an object 

that is not a connection. 


Concurrent Condition Codes 

After the Loader attempts the loading operation, it returns a condition 
code in the except$code field of the Loader Result Segment. The Loader 
can return the following condition codes in this manner. 

E$OK No exceptional conditions. 

E$BAD$GROUP The target file contains an invalid group 

definition record. 

E$BAD$SEGMENT The target file contains an invalid segment 

definition record. 
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E$CHECKSUM 

E$EOB* 

E$EXIST 

E$FIXUP 

E$FLUSHING 

E$IO$HARD 

E$IO$OPRINT 

E$ 10$ SOFT 

E$IO$UNCLASS 

E$IO$WRPROT 

E$LIMIT 

E$NO$LOADER$MEM 

E$NO$MEM 

E$NOSTART 

E$PARAM 

E$REC$FORMAT 

E$REC$LENGTH 

REPLACE 


At least one record of the target file contains a 
checksum error. 

The call encountered an unexpected end-of-file. 

The device containing the file to be loaded was 
detached before the loading operation was completed. 

The target file contains an invalid fixup record. 

The device containing the target file is being 
detached . 

A hard I/O error occurred. This means that another 
try is probably useless. 

The device containing the target file was 
off-line. Operator intervention is required. 

A soft I/O error occurred. This means that the I/O 
System tried to perform the operation and failed, 
but another try might still be successful. 

An unknown type of I/O error occurred. 

The volume is write-protected. 

The calling task’s job has already reached its 
object limit. 

The memory pool of the calling task does not 
currently have a block of memory large enough to 
allow the Loader to run. 

The Loader attempted to load PIC or LTL groups or 
segments, but the memory pool of the calling task’s 
job does not currently contain a block of memory 
large enough to accommodate these groups or 
segments . 

The target file does not specify the entry point 
for the program being loaded. 

The target file has a stack smaller than 16 bytes. 

At least one record in the target file contains a 
format error. 

The target file contains a record longer than the 
Loader’s internal buffer. The Loader’s buffer 
length is specified during the configuration of the 
Loader. See Chapter 3 and the iRMX 86 
CONFIGURATION GUIDE for information about 
configuring the Loader. 
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E$REC$TYPE 


E$SEG$BOUNDS 


At least one of the following is true: 

• At least one record in the target file is of a 
type that the Loader cannot process. 

• The Loader encountered records in a sequence 
that it cannot process. 

The Loader created a segment into which to load 
code. One of the data records specified a load 
address outside of that segment. 
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CONDITION CODES 

This system call can return condition codes at two different times. 
Codes returned to the calling task immediately after the invocation of 
the system call are considered sequential condition codes. Codes 
returned after the concurrent part of the system call has finished 
running are considered concurrent condition codes. The following list is 
divided into two parts — one for sequential codes and one for concurrent 
codes. 


Sequential Condition Codes 

The Loader returns one of the following condition codes to the WORD 
pointed to by the except$ptr parameter: 

E$OK No exceptional conditions. 

E$BAD$HEADER The target file does not begin with a valid 

header record for a loadable object module. 
Possibly the file is a directory. 

E$CHECKSUM The header record of the target file contains a 

checksum error. 

The Loader opened the connection, but some other 
task closed the connection before the loading 
operation was begun. 

The specified connection was already open. 

The calling task*s job is not an I/O job. 

At least one of the following is true: 

• The connection parameter is not a token for 
an existing object. 

• The calling task’s job has no global job. 

• The msg$mbox parameter does not refer to an 
existing object. 

The specified connection does not have ’’read” 
access to the file. 

E$FLUSHING The device containing the target file is being 

detached . 

E$IO$HARD A hard I/O error occurred. This means that 

another try is probably useless. 

E$IO$OPRINT The device containing the target file is 

off-line. Operator intervention is required. 


E$CONN$NOT$OPEN 

E$CONN$OPEN 

E$CONTEXT 

E$EXIST 


ElFACCESS 
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I 


E$IO$SOFT 

E$IO$UNCLASS 

E$IO$WRPROT 

E$JOB$PARAM 

E$JOB$SIZE 

E$LOADER$SUPPORT 

E$MEH 

E$NO$LOADER$HEM 

E$N0T$C0NFI6URED 

E$NOT$FILE$CONN 

E$NOUSER 

E$PARAM 

E$ SHARE 

E$ SUPPORT 

E$T1HE 

E$TYPE 


A soft I/O error occurred. This means that the 
I/O System tried to perform the operation and 
failed, but another try might still be successful. 

An unknown type of I/O error occurred. 

The volume is write-protected. 

The pool$upper$bound parameter is both non-zero 
and smaller than the pool$lower$bound parameter. 

The pool$upper$bound parameter is non-0 and too 
small for the target file. 

The target file requires capabilities not 

configured into the Loader. For example, the 
loader might be attempting to load PIC code when 
configured to load only absolute code. 

The memory available to the calling task's job or 
the Basic I/O System is not sufficient to 
complete the call. 

The memory pool of the newly created I/O job does 
not currently have a block of memory large enough 
to allow the Loader to run. 

This system call is not part of the present 
configuration. 

The specified connection is to a device rather 
than to a named file. 

The calling task's job does not have a default 
user, or the object cataloged under the logical 
name R?IOUSER is not a user object. 

The value of the except$mode field within the 
except$handler structure lies outside the range 0 
through 3. 

The calling task tried to open a connection to a 
file already being used by some other task, and 
the file's sharing attribute is not compatible 
with the open request. 

The specified connection was not created in this 
job. 

The calling task's job is not an I/O job. 

The connection parameter is a token for an object 
that is not a connection. 
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E$EXIST 

E$FACCESS 

E$FIXUP 

E$FNEXIST 

E$FLUSHING 

E$INVALID$FNODE 

E$IO$HARD 

E$IO$JOB 

E$IO$OPRINT 

E$IO$SOFT 

E$IO$UNCLASS 

E$IO$WRPROT 

E$JOB$PARAM 

E$JOB$SIZE 

E$LIMIT 


At least one of the following is true: 

o The msg$mbox parameter is not a token for an 
existing object. 

o The calling task’s job has no global job. 

o The device containing the target file was 
detached. 

The default user object for the new I/O job does 
not have ’’read” access to the specified file. 

The target file contains an invalid fixup record. 

The specified target file, or some file in the 
specified path, does not exist or is marked for 
deletion. 

The device containing the target file is being 
detached . 

The fnode for the specified file is invalid, so the 
file must be deleted. 

A hard I/O error occurred. This means that another 
try is probably useless. 

The calling task’s job is not an I/O job. 

The device containing the target file is off-line. 
Operator intervention is required. 

A soft I/O error occurred. This means that the I/O 
System tried to perform the operation and failed, 
but another try might still be successful. 

An unknown type of I/O error occurred. 

The volume is write-protected. 

The pool$upper$bound parameter is nonzero and 
smaller than the pool$lower$bound parameter. 

The pool$upper$bound parameter is nonzero and too 
small for the target file. 

At least one of the following is true: 

o The task$priority parameter is higher 
(numerically lower) than the newly-created I/O 
job’s maximum priority. This maximum priority 
is specified during the configuration of the 
Extended I/O System (if the job is a descendant 
of the Extended I/O System) or of the Human 
Interface (if the job is a descendant of the 
Human Interface) . 
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E$LOADER$SUPPORT 

E$MEM 

E$NO$LOADER$MEH 

ElNOHEH 

E$NOSTART 

E$NOT$CONFIGURED 

E$NOUSER 

E$PARAM 

E$PATHNAME$- 

SYNTAX 

E$REC$FORMAT 


• Either the newly created I/O job or its default 
user object is already involved in 255 
(decimal) I/O operations. 

The target file requires capabilities not 
configured into the Loader. For example, it might 
be attempting to load PIC when configured to load 
only absolute code. 

The memory available to the calling task’s job is 
not sufficient to complete the call. 

The memory pool of the newly created I/O job does 
not currently have a block of memory large enough 
to allow the Loader to run. 

The target file contains either PIC segments or 
groups, or LTL segments or groups. In any case, 
the memory pool of the new I/O job does not have a 
block of memory large enough to allow the Loader to 
load these records. 

The target file does not specify the entry point 
for the program being loaded. 

This system call is not part of the present 
conf igurat ion . 

The calling task's job does not have a default 
user, or the objcsct cataloged under the logical 
name R?IOUSER is not a user object. 

At least one of the following is true; 

• The value of the except$mode field within the 
except$handler structure lies outside the range 
0 through 3. 

• The target file requested a stack smaller than 
16 bytes. 

The specified pathname contains one or more invalid 
characters . 

At least one record in the target file contains a 
format error. 
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COMMAND PROCESSING 


DELETING THE COMMAND CONNECTION 


After you have finished invoking commands programmatically, you must 
delete the command connection. The C$DELETE$COMMAND$CONNECTION system 
call performs this operation. You do not need to delete the command 
connection after each command invocation, because the command connection 
is re-usable. However, you should delete the command connection after 
performing all C$SEND$COMMAND operations. This frees the memory used by 
the data structures of the command connection. 


EXAMPLE 


Figure 5-1 contains an example of a program that uses 
C$CREATE$COMMAND$CONNECTION, SEND$COMMAND , and 
DELETE$COMMAND$CONNECTION. It invokes the Human Interface COPY command 
programmatically. 




* * 

* This example demonstrates the use of the following Human Interface * 

* advanced standard functions: * 

* * 

* rq$C$create$command$connection * 

* rq$C$send$ command * 

* rq$C$delete$command$connection * 

* * 

* This program uses the previous system calls to invoke the command * 

* COPY : FI: OLD to ::F1:NEVI from within and then continue normal * 

* processing. The program is invoked with the command line: * 

it it 

* PROG2 * 


ititititititititititititititititititititititititititititititititititititititititititititititititititititititititititititititititititititititititit/ 

prog2: DO; 

$include (hexcep.lit) 

^include (hcrccn.ext) 
linclude (hsndcmd.ext) 

$include (hdlccn.ext) 
linclude (iexioj.ext) 

$include (hgtincn.ext) 

$ include (hgtocn.ext) 

DECLARE (ci$token, co$token, command$connection$token) WORD, 

(excep, comexcep, exexcep) WORD; 

DECLARE output$prep BYTE; 


Figure 5-1. Command Connection Example 
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COMMAND PROCESSING 


/* Invoke utility to copy file OLD to file NEW */ 

/* Get tokens for Cl and CO ’•'/ 

ci$token = rq$C$get$input$connection(@(4, * :CI: ’ ) , @excep) ; 

IF excep <> E$OK THEN 

CALL rq$exit$io$job (excep, 0, exexcc’.p); 

co$token = rq$C$get$output$connection(@(4, * :C0: ' ) » output$prep, 0excep); 
IF excep <> E$OK THEN 

CALL rq$exit$io$job (excep, 0, exexcep); 

/* Create command connection */ 

command$connection$tok = rq$C$create$command$connection (ci$token, 

co$token, 0, 
0excep ) ; 


/* Send command to copy files */ 

CALL rq$C$send$command ( command! connection$tok, 

0(23,*COPY :F1:0LD TO :F1:NEW*), 

0comexcep , @excep ) ; 

IF excep <> E$OK THEN 

CALL rq$exit$io$job (excep, 0, exexcep); 

/* Delete command connection 

CALL rq$C$delete$command$connection (command$connection$tok, 0excep); 
IF excep <> E$OK THEN 

CALL rq$exit$io$job (excep, 0, exexcep); 


Rest of program 


/* Finish I/O processing */ 

CALL rq$exit$io$job (excep, 0, 0exexcep); 

END prog2; 


Figure 5-1. Command Connection Example (continued) 
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Table B-3. Conditions And Their Codes (continued) 


Category/ 

Mnemonic 

Meaning 

Numeric Code 
Hex Decimal 

Human 

Interface Environmental Conditions (continued) 


ElCONTINUED 

The parse buffer contains a continuation 
character , 

83H 

131 

E$INVALID$- 

NUMERIC 

A numeric value contains invalid 
characters . 

84H 

132 

E$LIST 

A value in the value list is missing. 

85H 

133 

E$WILDCARD 

A wild-card character appears in an 
invalid context, such as in an inter- 
mediate component of a pathname. 

86H 

134 

E$PREPOSITION 

The command line contains an invalid 
preposition. 

87H 

135 

E$PATH 

The command line contains an invalid 
pathname . 

88H 

136 

E$CONTROL$C 

The user typed a CONTROL-C to abort the 
coiomand . 

89H 

137 

E$CONTROL 

The command line contains an invalid 
control. 

8AH 

138 

E$UNMATCHED$- 

LISTS 

The number of files in the input and 
output pathname lists is not the same. 

8BH 

139 

E$DATE 

The operator entered an invalid date. 

8CH 

140 

E$NO$PARAM- 

ETERS 

A command expected parameters, but 
the operator didn’t supply any. 

SDH 

141 

ElVERSION 

The Human Interface is not compatible 
with the version of the command the 
operator invoked. 

8EH 

142 

E$6ET$PATH$- 

ORDER 

A command called C$GET$OUTPUT$PATHNAME 
before calling C$GET$INPUT$PATHNAME 

8FH 

143 


UDI Environmental Conditions 



E$UNKNOUN$EXIT 

The program exited normally. 

0C0H 

192 
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HUMAN INTERFACE EXCEPTION CODES 


Table B-3. Conditions And Their Codes (continued) 


Numeric Code 


Category/ 

Mnemonic 

Meaning 

Hex 

Decimal 

UDI Environmental Conditions (continued) 

E$WARNING$EXIT 

The program issued warning messages. 

0C1H 

193 

E$ERROR$EXIT 

The program detected errors. 

0C2H 

194 

E$FATAL$EXIT 

A fatal error occurred in the program. 

0C3H 

195 

E$ABORT$EXIT 

The Operating System aborted the 
program. 

0C4H 

196 

E$UDI$INTERNAL 

A UDI internal error occurred. 

0C5H 

197 

Nucleus Programmer Errors 

* E$ZERO$- 
DIVIDE 

A task attempted a divide in which 
the quotient was larger than 16 bits. 

8000H 

32768 

* E$OVERFLOW 

An overflow interrupt occurred. 

8001H 

32769 

E$TYPE 

A token parameter referred to an 
existing object that is not of the 
required type. 

8002H 

32770 

E$PARAM 

A parameter that is neither a token 
nor an offset has an invalid value. 

8004H 

32772 

E$BAD$CALL 

An OS extension received an invalid 
function code. 

8005H 

32773 

* E$ARRAY$- 
BOUNDS 

Hardware or software has detected an 
array overflow. 

8006H 

32774 

* E$NDP$ERROR 

A Numeric Processor Extension (NPX) 
error has occurred. OS extensions 
can return the status of the NPX to 
the exception handler. 

8007H 

32775 

* E$ILLE6AL$- 
OPCODE 

The iAPX 186 or 286 processor tried 
to execute an invalid instruction 

8008H 

32776 

* For iAPX 2 

condition. 

586-based systems, a CPU trap caused thi 

s exceptional 
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UDI SYSTEM CALLS IN THE iRMXA 86 ENVIRONMENT 


The key to using iRMX 86 files is the connection . A program wanting to 
use a file first obtains (a token for) a connection to the file and then 
uses the connection to perform operations on the file. Other programs 
can simultaneously have their own connections to the same file. Each 
program having a connection to a file uses its connection as if it has 
exclusive access to the file. 

A program obtains a connection by calling DQ$ATTACH (if the file already 
exists) or DQ$CREATE (to create a new file). When the program no longer 
needs the connection, it can call DQ$DETACH to delete the connection. To 
delete both the connection and the file, the program calls DQ$DELETE. 

Once a program has a connection, it can call DQ$OPEN to prepare the 
connection for input/output operations. The program performs input or 
output operations by calling DQ$READ and DQ$WRITE. It can move the file 
pointer associated with the connection by calling DQ$SEEK. When the 
program has finished doing input and output to the file, it can close the 
connection by calling DQ$CLOSE. Note that the program opens and closes 
the connection , not the file. Unless the program deletes the connection, 
it can continue to open and close the connection as necessary. 

If a program calls DQ$DELETE to delete a file, the file cannot be deleted 
while other connections to the file exist. In that case, the file is 
marked for deletion and is not actually deleted until the last of the 
connections is deleted. During the time that a file is marked for 
deletion, no new connections to it may be created. 


CONDITION CODES AND EXCEPTION HANDLING CALLS 

Every UDI call except DQ$EXIT returns a numeric condition code specifying 
the result of the call. Each condition code has a unique mnemonic name 
by which it is known. For example, the code 0, indicating that there 
were no errors or unusual conditions, has the name E$OK. Any other 

condition means there was a problem, so these conditions are called 
exceptions . 

Exception conditions are classified as: 

• Environmental Conditions . These are generally caused by 
conditions outside the control of a program; for example, device 
errors or insufficient memory. 

• Programmer Errors . These are typically caused by mistakes in 
programming (for example, ’’bad parameter”), but ”divide-by-zero”, 
’’overflow”, ’’range check”, and errors detected by the 8087 80287 
Numeric Processor Extension (hereafter referred to generically as 
the NPX ) are also classified as programmer errors. 

The iRMX 86 NUCLEUS REFERENCE MANUAL contains a list of condition codes 
that the iRMX 86 Operating System can return, with the mnemonic and 
meaning of each code. 
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UDI SYSTEM CALLS IN THE iKMXi 86 ENVIRONMENT 


If the default value (NEVER) for the EM parameter in the Nucleus ICU 
screen is in effect when a system call generates an exception condition, 
the system simply returns the error code through the appropriate system 
call parameter. If you have specified YES as the value of the EM 
parameter in the Nucleus ICU screen, the default system exception handler 
(DEF.EXCEPTIONHANDLER) displays the appropriate error message at the 
console and terminates the program. However, your program can establish 
its own exception handler by calling DQ$TRAP$EXCEPTION . The exception 

handler can interpret condition codes that are returned by calling 
DQ$DECODE$EXCEPTION . The rest of this section provides some facts that 
you need in order to write your own exception handler. 

After an exception condition occurs and before your exception handler gets 
control, the iRMX 86 Operating System does the following: 

1. Pushes the condition code onto the stack of the program that made 
the system call having the exception condition. 

2. Pushes the number of the parameter that caused the exception onto 
the stack (1 for the first parameter, 2 for the second, etc.). 

3. Pushes a word onto the stack (reserved for future use). 

4. Pushes a word for the NPX onto the stack. 

5. Initiates a long call to the exceiption handler. 

If the condition was not caused by an erroneous parameter, the responsible 
parameter number is zero. If the exception code is E$NDP, the fourth item 
pushed onto the stack is the NPX status word, and the NPX exceptions have 
been cleared. 

Programs compiled under the SMALL model of segmentation cannot have an 
alternate exception handler, but must use the default system exception 
handler. This is because alternate exception handlers must have a LONG 
POINTER, which is not available in the S!([ALL model. 


MAKING UDI CALLS FROM PL/M-86 AND ASM86 PROGRAMS 


This section describes how to make UDI calls from a program, using the 
DQ$ALLOCATE system call as an example. You can easily generalize from 
this example to see how to make the other UDI calls. There are two 

examples: one for a call from a PL/M-86 program and one for a call from 

an ASM86 program. 

The way this chapter shows the DQ$ALLOCATE system call syntax is the 
following: 

base$addr = DQ$ALLOCATE (size, except$ptr) ; 

There are three parameters: size (which has the WORD data type), 

except$ptr (which has the POINTER data type) , and base$addr (which has 
WORD data type or the SELECTOR data type, depending on the version of 
PL/M-86 ) . 
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UDI SYSTEM CALLS IN THE iRMXi 86 ENVIRONMENT 


Each of the examples that follow request 128 bytes of memory and point to 
a WORD named ”ERR** where the condition code is to be returned. 

EXAMPLE PL/M-86 CALLING SEQUENCE 

DECLARE ARRAY_BASE WORD, (or SELECTOR) 

ERR WORD; 

ARRAYBASE = DQ$ALLOCATE (128, @ERR) ; 


EXAMPLE ASM86 CALLING SEQUENCE 


MOV AX, 128 

PUSH AX ; first parameter 

LEA AX, ERR 

PUSH DS ; second parameter 

PUSH AX ; 

CALI. DQALLOCATE 

MOV ARRAYBASE, AX ; returned value 


This example is applicable to programs assembled according to the COMPACT, 
MEDIUM, and LARGE models of segmentation. For the SMALL model, omit 
pushing the DS segment register. 


DESCRIPTIONS OF SYSTEM CALLS 

This section contains descriptions of the UDI system calls, which are 
arranged alphabetically. Every system call description contains the 
following information in this order: 


• The name of the system call. 

• A brief summary of the function of the call. 

• The form of the call as it is invoked from a PL/M-86 program, with 
symbolic names for each parameter. 

• Definition of input and output parameters. 

• A complete explanation of the system call, including any 
information you will need to use the system call. 
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DQSALLOCATE 


UDI SYSTEM CALLS IN THE ililMXA 86 ENVIRONMENT 


DQ$ALLOCATE 


DQ$ALLOCATE requests a memory segment from the free memory pool. 


base$addr = DQ$ALLOCATE (size, except$ptr) ; 


INPUT PARAMETER 

size A WORD which, 

if not zero, contains the size, in bytes, of 
the requested segment. If the size parameter 
is not a multiple of 16, it will be rounded up 
to the nearest multiple of 16 before the 
allocation request is processed. 

if zero, indicates that the size of the request 
is 65536 (64K) bytes. 


OUTPUT PARAMETERS 

base$addr A SELECTOR, into which the Operating System places 

the base address of the memory segment. If the 
request fails because the memory requested is not 
available, this value will be 0FFFFH, and the 
system will return an E$MEM exception code. 

except$ptr A POINTER to a WORD where the system places the 

condition code. Condition codes are described in 
Appendix B. 


DESCRIPTION 

The DQ$ALLOCATE system call is used to request additional memory from the 
free space pool of the program. Tasks may use the additional memory for 
any desired purpose. 
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UDI SYSTEM CALLS IN THE iRMXi 86 ENVIRONMENT 


DQ$TRUNCATE 


DQ$TRUNCATE moves the end-of-file to the current position of a named file 
connection’s file pointer, thereby freeing the portion of the file lying 
beyond the file pointer. 


CALL DQ$TRUNCATE (connection, except$ptr) ; 


INPUT PARAMETER 

connection A TOKEN for a connection to the named data file 

that is to be truncated. The file pointer of this 
connection marks the place where truncation is to 
occur. The byte indicated by the pointer is the 
first byte to be dropped from the file. 


OUTPUT PARAMETER 

except$ptr A POINTER to a WORD where the system places the 

condition code. Condition codes are described in 
Appendix B. 


DESCRIPTION 

This system call truncates a file at the current setting of the file 
pointer and releases all file space beyond the pointer for reallocation 
to other files. If the pointer is at or beyond the end of file, no 
truncation is performed. Unless the file pointer is already at the 
proper location, your program should use the DQ$SEEK system call to 
position the pointer before calling DQ$TRUNCATE. 

The connection should have write, or read and write access rights, 
established when the connection was opened. 
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UDI SYSTEM CALLS IN THE iPHXA 86 ENVIRONMENT 


DQlURITE 


The DQ$WRITE system call copies a collection of bytes from a buffer into 
a file. 


CALL DQ$WRITE (connection, buff$ptr, count, except$ptr; 


INPUT PARAMETERS 

connection A TOKEN for the connection to the file into which 

the information is to be written. 

buff$ptr A POINTER to a buffer containing the data to be 

written to the specified file. 

count A WORD containing the number of bytes to be 

written from the buffer to the file. 


OUTPUT PARAMETER 

except$ptr A POINTER to a WORD where the system places the 

condition code. Condition codes are described in 
Appendix B. 


DESCRIPTION 

This system call causes the Operating System to write the specified 
number of bytes from the buffer to the file. 


Connection Requirements 

If the connection is not open for writing or updating, DQ$WRITE returns 
an exception code. 
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INDEX (continued) 


long-term operations 5-8 
modem 7-8 

name of device-unit 2-2 
notify procedure 2-14, 5-6 
numbering of devices 1-2 

open requests 4-2 

parity 7-7 

PL/M-86 iii, 5-11, 8-1 
portable device drivers 3-14 
priority 3-9 

QUEUE$IO procedure 2-5, 3-3, 6-3, A-5 

RAD$ procedure-name prefix (iRMX 88 systems only) 3-2, A-1 

random access device drivers 1-3, 5-1 

random access devices 3-1 

random access driver example 6-8 

read requests 4-2 

request queue 6-5 

requests 1-3 , 4-1 

requirements for using the common device driver 3-1 
retry limit 3-11 

RQ$A$PHYSICAL$ATTACH$DEVICE system call 2-3, 3-4, 3-5, 6-4, A-1 
RQ$ELVL system call A-9 
RQlFORMAT system call 5-11 
RQ$SET$ INTERRUPT system call A-9 

SEEK$COMPLETE procedure 3-11, 5 ^ 
seek requests 4-2 

set output waiting (XTS$SET$0UTPUT$WAITIN<3) procedure 7-18, 7-24 

signal character 2-15 

source files, device drivers B-1 

special requests 4-2 

stack size 3-9 

support (INCUDE) files B-55 


I 


I 


tape drives 2-14, 5-8 
rewinding of 5-8 
terminal 

attributes 2-15 
baud rate 7-16, 7-19 

Device Information Table 2-5, 7-3 . 7-27 

devices 3-3 

driver example B-29 

drivers 7-1 

flags Idl, 7-14 

modem 7-8 

parity 7-7 

Unit Information Table 7-6 

terminal answer (TERM$ANSWER) procedure 7-17, 7-20 . 7-27 
terminal check (TERH$CHECK) procedure 7-17, 7-22 . 7-27 
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INDEX (continued) 


terminal controller data 7-14 . 7-27 

terminal finish (TERM$FINISH) procedure 7-17, 7-19 . 7-27 

terminal hangup (TERH$HAN6UP) procedure 7-17, 7-21 . 7-27 

terminal initialization (TERM$INIT) procedure 7-17, 7-18 . 7-27 

terminal output (TERM$OUT) procedure 7-17, 7-24 . 7-27 

terminal setup (TEEIM$SETUP) procedure 7-17, 7-19 . 7-27 

Terminal Support Code 7-11 

terminal unit data 7-4, 7-14, 7-27 

track size 3-11 

types of device drivers 1-3 

Unit Information Table 2-5, 3-10 . 7-6 
unit number 1-2 . 2-5, 2-11 
unit status codes 2-10 
updating output to a device 2-6 
using DUIBs 2-7 

volume granularity 2-7 

write requests 4-2 

X8274.P86 terminal driver source file B-29 
XTS$SET$OUTPUT$WAITING procedure 7-24 
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CHAPTER 6 
SIMPLIFYING CONFIGURATION 
DURING DEVELOPMENT 


For your convenience, the configuration information found in this chapter 
has been added to the iRMX 86 CONFIGURATION GUIDE. For any information 
that you might need concerning the following topics, refer to the iRMX 86 


CONF 


GURATION GUIDE. 


Data segments 
Configuration 

Freezing locations of entry points 

The Interactive Configuration Utility (ICU) 

The LOC86 command 

Freezing the Base of the Data Segment 


I 

I 
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CHAPTER 2 

USING A TERMINAL WITH THE IRMX™ 86 

OPERATING SYSTEM 


When you are using a terminal with the iRMX 86 Operating System, you must 
limit the maximum priority of your tasks or they could interfere with the 
proper functioning of your terminal. High priority processor-bound tasks can 
cause the Terminal Handler to drop input characters. 

While using a terminal that is under control of the Terminal Handler, an 
operator either reads an output message from the terminal’s display or enters 
characters by striking keys on the terminal’s keyboard. Normal input 
characters are those destined for input messages that are sent to tasks. 
Special input characters direct the Terminal Handler to take special actions. 
The special characters are RUBOUT, Carriage Return, Line Feed, ESCape, 
control-C, control-0, control-Q, control-R, control-S, control-X, and 
control-Z. The output-only version of the Terminal Handler does not support 
any of the special characters. In the remainder of this chapter, the handling 
of these two types is discussed, and the significance of each of the special 
characters is explained. 


NOTE 

This chapter contains several references 
to mailboxes and request messages used 
by tasks to communicate with the 
terminal. If you are puzzled by such a 
reference, look in Chapter 3 for an 
explanation. 


HOW NORMAL CHARACTERS ARE HANDLED 


The destination of a normal character, when entered, depends on whether 
there is an input request message at the Terminal Handler’s input request 
mailbox. If there is an input request message, the character is echoed 
to the terminal’s display and goes into the input request message. If 
there is not an input request message, the character is deleted. 


HOW SPECIAL CHARACTERS ARE HANDLED 


Table 2-1 lists the special characters and summarizes the effects of each 
of them. The following text comprises complete descriptions of the 
effects of the special characters. In these descriptions, there are 
several references to ’’the current line.” The current line consists of 
the data, with editing, that has been entered since the last end-of-line 
character . 
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USING A TERMINAL WITH THE IRMXA 86 OPERATING SYSTEM 


Table 2-1. Special Character Sutranary 


Special 

Character 

Effect 

RUBOUT 

Deletes previously entered character. 

Carriage 

Return 

Signals end of line. 

Line Feed 

Signals end of line. 

Escape 

Signals end of line. 

control-C 

Calls an application program. 

control-0 

Kills or restarts output. 

control-Q 

Resumes suspended output. 

control-R 

Displays current line with editing. 

control-S 

Suspends output. 

control-X 

Deletes the current line. 

control-Z 

Sends empty message. 


The following descriptions concern the special characters needed when 
entering data at the terminal. Most of these characters are for 
line-editing. Each description is divided into two parts: internal 
effects and external effects. The difference is that internal effects are 
those that are not directly visible,, whereas external effects are 
immediately shown on the terminal’s display. 


RUBBING OUT A PREVIOUSLY-TYPED CHARACTER (RUBOUT) 

Internal Effects: Causes the most recently entered but not yet deleted 

character to be deleted from the current line. If the 
current line is empty, there is no internal effect. 
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CHAPTER 3 

PROGRAMMING CONSIDERATIONS 


The IRMX 86 Terminal Handler supports terminal input and output by 
providing mailbox interfaces. Figure 3-1 shows the use of these 

mailboxes. In the figure, an arrow pointing from a task to a mailbox 
represents an RQ$SEIND$MESSAGE system call. An arrow pointing from a 
mailbox to a task indicates an RQ$RECEIVE$MESSAGE system call. 


PROVIDED 
BY USER 


PROVIDED 
BY USER 



x-601 


Figure 3-1. Input and Output Mailbox Interfaces 


The protocol that tasks observe is much the same for input and output. 
In each case, the task initiates I/O by sending a request message to a 
mailbox. An input request mailbox (default name RQTHNORMIN) and an 
output request mailbox (default name RQTHNORMOUT) are provided. These 
mailboxes are cataloged in the root job directory. In the case of 
multiple terminals, one input and one output mailbox will be cataloged 
for each Terminal Handler. (See Chapter 4 for more information about 
multiple versions of the Terminal Handler.) Figure 3-2 illustrates the 
protocol for finding the root job token and for obtaining the input and 
output mailbox tokens. 
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PROGRAMMING CONSIDERATIONS 


* This example illustrates the protocol for finding the root job token * 

* and for obtaining the input and output mailbox tokens. * 

*********************)»f5«ci»t******)ic***Vic***)«c)«c;i«c*)>cV^?ic*:>C)ic*)i(**)ic*******Vic*Vic*>«c:*c*****yc* 


DECLARE 

rtjb$ token 

WORD; 

DECLARE 

root$job 

LITERALLY ' 3 * ; 

DECLARE 

status 

WORD; 

DECLARE 

input$mbx$token 

WORD; 

DECLARE 

wait$forever 

LITERALLY ’0FFFFH' ; 


/*By setting the input parameter to three, the GET$TASK$TOKEN primitive 
will return the root job's TOKEN.*/ 

rtjb$ token = RQ$GET$TASK$TOKENS (root$job, 

^status) ; 


/*The following LOOKUP$OBJECT primitives use the default mailbox names.*/ 

input$mbx$ token = RQ$LOOKUP$OBJECT (rtjb$ token, 

0(10, 'RQTHNORMIN'), 
wait$forever, 

0status) ; 

output$mbx$token = RQ$LOOKUP$OBJECT (rtjb$ token, 

0(11, 'RQTHNORMOUT'), 
wait$forever, 

0status) ; 


Figure 3-2. Protocol for Obtaining Root Job and Mailbox Tokens 


Refer to the iRMX 86 NUCLEUS REFEREN(3E MANUAL for more information 
concerning the individual primitives used in the previous example. VJhen 
a task sends a message to the Terminal Handler mailbox, the Terminal 
Handler processes the request and then sends a response message back to 
the requesting task. The task waits at a response mailbox for the 
message. Thus, whether a task does input or output, it first sends and 
then receives. The full details of the input and output protocols are 
described later in this chapter. Output is discussed first because it is 
somewhat easier to understand. 

For both input and output, a task sends a message segment to the Terminal 
Handler. The format of a request message is depicted in Figure 3-3. The 
numbers in that figure are offsets, in bytes, from the beginning of the 
segment. The field names have differcsnt meanings for input and for 
output. For both input and output, the first four fields are WORD 
values. The MESSAGE CONTENT field can be up to 132 bytes in length for 
input and up to 65527 bytes in length for output. 
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SPECIFIC MODIFICATIONS TO INDIVIDUAL INTEL CONTROLLER BOARDS 


Table 6-7. Controller Board Switch Settings (continued) 


Intel Board 

Switch Setting 

Description/Function 

iSBC 220 
(DIP Switches) 

51, 1-7 OFF 

8 ON 

52 , 1-2 ON 
3-10 OFF 

Selects port address 100H. 

Selects a 16-bit bus and 
16-bit address decoding. 
Selects port address 100h. 

iSBC 220 
(Wire Wraps) 

E16 - E15 

E18 - E17 
E20 - E19 

Selects port address 100H 

Selects a 16-bit bus and 
16-bit address decoding 

iSBX 251 


Not applicable. 

iSBC 254 


Not applicable. 

iSBC 254S 


Not applicable. 

iSBX 270 


Not applicable. 

iSBX 351 


Not applicable. 

iSBC 534 


Not applicable. 

iSBC 544 

SWl, 1-4 ON 

SWl , 5 ON 

SWl , 6 OFF 

SWl , 7 ON 

SWl , 8 OFF 

If your board does not 
have a switch SWl, then 
refer to Table 6-3. 

Selects Dual-Port RAM 

address. Also refer to 

Table 6-4. 

Selects Dual-Port RAM size 
of 16K. 

Selects 2732A EPROMS. 

Configures board for slave 
mode. 
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SPECIFIC MODIFICATIONS TO INDIVIDUAL INTEL CONTROLLER BOARDS 


DIP HEADER CONFIGURATIONS FOR THE RS232C PROTOCOL 

Table 6-8 lists the DIP-header configurations you need to supply to 
implement the RS232C serial protocol. This configuration process 
involves either soldering wires on a solder style header or inserting 
wires into a pin-and-socket style header. 


Table 6-8. DIP Header Configurations for the RS232C Protocol 


Intel Board 

DIP Header 
Jumpers 

Description/Function 

iSBX 351 

3-13 

Board RxD to Terminal TxD. 


4-14 

Board TxD to Terminal RxD. 


7-8 

Board DSR to Board DTR. 


5-6 

Board RTS to Board CTS. 


11-12 

Terminal RTS to Terminal CTS. 


9-10 

Terminal DSR to Terminal DTR. 

iSBC 534 

4-5 

Board DSR to Board DTR. 


6-7 

Board RTS to Board CTS. 


8-10 

Board RxD to Terminal TxD. 


9-11 

Board TxD to Terminal RxD. 


12-13 

Terminal RTS to Terminal CTS. 


14-15 

Terminal DSR to Terminal DTR. 

iSBC 544 

2-3* 

Board DSR to Board DTR. 


4-5 

Board RTS to Board CTS. 


6-12 

Board RxD to Terminal TxD. 


7-13 

Board TxD to Terminal RxD. 


14-15 

Terminal RTS to Terminal CTS. 


16-17* 

Terminal DSR to Terminal DTR 

Notes: Signal Names: 


TxD: Transmit Data 

RxD: Receive Data 

DTR: Data 

Terminal Ready 

DSR: Data Set Ready 

RTS: Request To Send 

CTS: Clear To Send 


* If your terminal does not produce DSR but receives DTR, replace 
with the following; 2-16; 3-17 

MISCELLANEOUS JUMPERS 

Table 6-9 lists jumpering information not covered in the previous 
sections. The list of jumpers change different functional areas. 
Perform the changes to use default values: established by Intel. 
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SPECIFIC MODIFICATIONS TO INDIVIDUAL INTEL CONTROLLER BOARDS 


Table 6-9. Miscellaneous Jumpers 


Intel Board 

Remove 

Jumper 

Add 

Jumper 

Description/Function 

iSBC 204 

E75-E76 

E77-E78 


Use if iSBC 204 has two 8271 
devices installed. 

iSBC 206 



None. 

iSBC 208 



None. 

iSBC 215 

W4, 1-2 


Remove only if installing an 
iSBX 218A in iSBX socket 1 
(J4). 

iSBC 215G 

W4, 1-2 


Remove only if installing an 
iSBX 218A in iSBX socket 1 
(J4). 



W24, 1-2 

Use if installing an iSBX 
218(A) in iSBX socket 1 (J4). 



W20, 1-2 

Connects -12 volts from the 
MULTIBUS to the iSBC 215G. 

iSBX 218 

Wl, A-B 

Wl, A-C 

Disables iSBX 218 DMA lines. 

iSBX 218A 



This board may require some 
special jumper changes 

depending on the require- 
ments of your application. 
Consult the iSBX 218A 

Hardware Reference Manual for 
special considerations. 

iSBC 220 



None. 

iSBX 251 



None. 

iSBC 254 



None. 

iSBC 254 S 



None. 
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SPECIFIC MODIFICATIONS TO INDIVIDUAL INTEL CONTROLLER BOARDS 


Table 6-9. Miscellaneous Jumpers (continued) 


Intel Board 

Remove 

Jumper 

Add 

Jumper 

Description/Function 

iSBX 270 

E11-E12 

E16-E17 

E21-E22 

E23-E24 


Sets up your terminal screen 
output . 

iSBX 351 



None. 

iSBC 534 



None. 

iSBC 544 



None. 
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CHAPTER 1 0 
DEVICE DRIVER PARAMETERS 


This chapter discusses how to respond to the prompts that appear on the Intel 
Device Driver screens. If you are using this chapter to understand a 
particular parameter line, search Table 10-1 for the device driver that 
interests you and then turn to the page indicated to the right of the device 
driver. 


Table 10-1., Intel-Supplied Device Drivers 


Device Driver 

Page Number 

iSBC 204 

10-02 

iSBC 206 

10-12 

iSBC 208 

10-21 

iSBC 215 

10-34 

iSBX 218 

10-50 

iSBC 220 

10-62 

iSBC 254 

10-76 

iSBX 270 

10-86 

iSBC 534 

10-95 

iSBC 544 

10-106 

8251A Terminal Driver 

10-118 

Line Printer 

10-130 

USART Terminal Handler Driver 

10-133 

8274 Terminal Driver 

10-135 

Line Printer for iSBC 286/10 

10-152 

iSBC 188/48 

10-152.1 

iSBX 251 

10-156 

SCSI Driver for iSBC 186/03 

10-164 

iSBX 218A 

10-179 

RAM Driver 

10-191 

iSBC 216 

10-200 

82530 Terminal Driver 

10-201 


If you are adding a user-supplied device driver, refer to page 10-214. 
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iSBCi 204 DRIVER PARAMETERS 

The iSBC 204 flexible disk driver: 

• Supports 8-inch, single-sided, single-density diskettes. 

• Supports the READ, WRITE, SEEK, SPECIAL, ATTACH$DEVICE , and 
DETAGH$DEVICE functions . 

• Accepts functions OPEN and CLOSE but performs no operations for 
them. 

Track formatting and volume change notification are supported via the 
SPECIAL function. Refer to the iRMX 86 BASIC I/O SYSTEM REFERENCE MANUAL 
for further information about these special functions. 

The iSBC 204 driver supports up to four units per controller, two for 
each 8271 flexible disk controller component. The typical controller has 
one 8271 component. This component supports two single-sided units. 

There are three screens that define th(s interface between the iSBC 204 
random access device driver and the I/O system. These screens relate to 
the three device configuration tables: the device information table, the 

unit information table, and the device unit information block (DUIB). 
Refer to Appendix D for further information about these tables. 

The values shown on the screens in this section are the same as values 
you would see if you choose option ”0” from the Intel-supplied device 
driver screen. 


iSBCl 204 DRIVER SCREEN 

The ICU uses the information from the following screen to create a device 
information table for the iSBC 204 driver. If your system includes more 
than one iSBC 204 controller, you must specify a unique interrupt level 
and port address for each controller. 


*** 



*** 

*** 



*** 

*** 



*** 

*** 

iSBG 204 Driver 


*** 

Tkick 

(ID Interrupt Level [Encoded Level] 

0018H 

*** 

*** 

(ITP) Interrupt Task Priority [0-0FFH] 

0082H 

*** 

*** 

(PA) Port Address [0-0FFFFH] 

00A0H 

*** 

*** 



*** 


Enter Changes [Abbreviation ?/= new_value] : 


. *** 

**** » 

Do you have any units for this device? 


j **** 

***** » 



1 ***** 
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iSBC® 208 


pool, so by setting this parameter to 0FFH you allow the calling job to 
select the number of buffers based on its own memory pool size. It is 
recommended that you use the default value. 


*****:^)<c*******5>c***:fc)>f**yic*****:k**y<)lit:«c*:*c****'!*c**5<c5iici«c****)ic)«cVt**:*c*yci«c)/ici*c**yc**:(>c)*c**)>c* 

* Do you have any more DUIBs for this device? * 

***:k****A***:«c*i>c*****y<*)>c*:<(^:*i'iii<*5<c*:ifc**5«c***yic**)iC5«tVic)«c***5iic****5«c***i*c>«c)iicyc)it*)«ci*cyc**Vic**yc 

Respond "Yes” to this prompt "Do you have any more device-unit 
information blocks for this device?" if you plan to use the iSBC 208 
controller with two devices that have different characteristics. 

While developing your initial systems, jrou can create as many device-unit 
information blocks as you want. The number of DUIBs can exceed the 
number of devices on your system. The particular DUIB associated with 
the device depends on the physical name you use when attaching it. Once 
you know that you will never need a particular DUIB, save memory by 
deleting it from your description file before you generate your 
configuration files (refer to Chapter 17 for additional information on 
generating configuration files). 
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iSBC 215 


iSBCi 215 DRIVER PARAMETERS 


The iSBC 215 Winchester disk driver: 

• Supports the READ, WRITE, SEE‘.K, SPECIAL, ATTACH$DEVICE , and 
DETACH$DEVICE functions. 

• Accepts the OPEN and CLOSE functions but performs no operations 
for it. 

Track formatting and volume change notification are supported via the 
SPECIAL function. Refer to the iRMX 86 BASIC I/O SYSTEM REFERENCE MANUAL 
for further information about these special functions. 

There are three screens that define the interface between the iSBC 215 
random access device driver and the I/O system. These screens relate to 
the three device configuration tables: the device information table, the 

unit information table, and the device unit information block (DUIB) . 
Refer to Appendix D for further information about these tables. 

The three screens that are described in this section are labeled 
”iSBC 215/218”. This means that the screen supports both the iSBC 215 
and the iSBX 218 controllers. This section describes only the 
iSBC 215-related parameter lines. Refer to the section of this chapter 
labeled ”iSBX^" 218 DRIVER PROMPTS" for information on how to respond to 
iSBX 218-related parameter lines. 

The values shown on the screens in this section are the same as values 
you would see if you use the rmx86.def file when you invoke the ICU. 


iSBCl 215 DRIVER SCREEN 

The ICU uses the information from the following screen to create a device 
information table for the iSBC 215 driver. If your system includes more 
than one iSBC 215 controller, you must specify a unique interrupt level 
and wakeup I/O port address for each controller. 


*** *** 

iSBC 215 /iSBX 218 Driver 

(IL) Interrupt Level [Encoded Level] 0058H 

(ITP) Interrupt Task Priority [0-0FFH] 0082H 

(IP) Wakeup I/O Port [0-0FFFFH] 0100H 

*** *** 

*** . Enter Changes [Abbreviation ?/= iiew_value] : . *** 

**** ♦ j ye*** 

®A*5*C*» 


***)»C*****5«C****)«C**********************',«C5«C*)IC******5lC*)«C******5<C5«C****1»C*** 

®*****5lC*5«C**1*C**5«C*****llO>C**3»C***********:IC***)lolC5lC1«C***:IC)«t*******5«C*5«C*5lC**® 
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iRMX™ 86 OPERATING SYSTEM RELEASE 6 CHANGE PACKAGE: UPDATE 2 


Purpose 

The change pages in this package correct technical errors identified in the 
current version of the iRMX^" 86 Release 6 documentation. 


Scope 

The following manuals are affected by this change package: 

Introduction and Operator’s Reference Manual (146194-001) 
Programmer’s Reference Manual, Part I (146195-001) 
Programmer’s Reference Manual, Part II (146196-001) 
iRMX’" 86 Installation and Configuration Guide (146197-001) 


Installation Instructions 

Change pages in the Update Package are accumulated from quarter to quarter. 

The change pages for each successive update are separated in this package by a 
blue cover page (similar to the sheet you are now reading). Within each 
update section, yellow, pink, green, and orange cover sheets segregate the 
change pages according to volume. 

The change pages in this package are installed by removing a page from your 
documentation and replacing it with the corresponding page from the change 
package. 

If this is the first iRMy" 86 Release 6.0 Update to be installed in your 
documentation: 


1. Install the change pages in this section before installing the change 
pages for Update 3. 


If you have installed previous iRMy" 86 Release 6.0 Updates in your 
documentation ; 


1 . 


Discard this section. 



IRMX^ 86 Release 6 . 0 Change Package : Update 2 
Change Pages for: 
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USING THE HUMAN INTERFACE 


Another advantage of hierarchical file structure is that duplicate file 
names are permitted unless the files reside in the same directory. 

Notice in Figure 2-2 that the file tree contains two directories named 
BILL. (These directories are on the extreme left and extreme right of 
the figure.) However, the Operating System recognizes them as unique 
files because each resides in a different directory. 

Each file tree resides on a secondary storage volume — the storage 
medium that contains the data. Examples of volumes include flexible 
diskettes, hard disks, and bubble memories. Before you can place named 
files on a volume, you must format the volume to accept named files. The 
formatting process writes a number of data structures on the volume to 
aid the Operating System in creating and maintaining files. You can use 
the FORMAT command (described in Chapter 3) to format your volumes. 

The uppermost point of each file tree is a directory called the root 
directory . When formatted for named files, each secondary storage volume 
has one and only one root directory. For these reasons: 

• There can be only one file tree per secondary storage volume. 

• A file tree cannot extend to more than one volume. 


PATHNAMES 

This section describes how to specify a particular file in a named-file 
tree. For simplification, it assumes that all files reside in the same 
file tree, and thus in the same volume. To identify the volume as well 
as the file, you must include a logical name for the device as the first 
portion of the file specification. Refer to the "Logical Names" section, 
later in this chapter, for more information about logical names. 

In a file tree, each file (data or directory) has a unique shortest path 
connecting it to the root directory. For example, in Figure 2-2, the 
shortest path from the root directory to file BATCH-2 goes through 
directory DEPTl, through directory TOM, through directory TEST-DATA, and 
finally stops at data file BATCH-2. When you want to perform an 
operation on a file (for example, using the COPY command to copy one file 
to another), you must specify not only the file's name, but the path 
through the file tree to the file. This description is called the file's 
pathname . For file BATCH-2 in Figure 2-2, the pathname is: 

DEPT 1 /TOM/TES T-DATA/BATCH- 2 
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USING THE HUMAN INTERFACE 



I I = directory 
/\ = data file 
L = list access 
R == read access 


N = no access 


DLAC - all access 


Figure 2-3. File Structure on an Intel Supplied Start-Up System 
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ATTACH DEVIC 


• A task deletes the connection to the file via a Basic I/O System 
or Extended I/O System call (r€‘fer to the IRMX 86 BASIC I/O 
SYSTEM REFERENCE MANUAL or the iRMX 86 EXTENDED I/O SYSTEM 
REFERENCE MANUAL for more information about connections). In 
this instance, the logical name remains cataloged in the global 
directory, but the connection to which it refers does not exist, 

• A user forcibly detaches the volume containing the file via the 
DETACHDEVICE command (described later in this chapter). 

• A user removes the volume from the drive. 


ERROR MESSAGES 

• <logical name> , list of logical names not allowed 

You entered more than one logical name as input to ATTACHE ILE , 

• <pathname>, list of pathnames not allowed 

You entered more than one pathname as input to ATTACHFILE , 

• <logical name> , logical name not allowed 

You attempted to attach a file using a logical name :HOME: , :CI; , 
or ;C0:. You cannot change the meaning of these logical names, 

• <logical name>, not a file connection 

The logical name you specified, <logical name> , is already 
cataloged in object directory of the session and does not 
represent a connection object. 

• <pathname>, not allowed as default prefix 

You attempted to attach a physical or stream file as your default 
prefix (:$:). Only named files are valid. 


• <logical name> , too many logical names 

Your global object directory is full. Therefore ATTACHFILE is 
unable to catalog the file's name in the object directory. 
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BACKUP 



This command saves files on a named voliame by copying them to a physical 
volume which serves as a backup storage device. This command provides a 
way of saving a large volume (a Winchester disk, for example) onto a 
number of smaller volumes such as diskettes or onto another mass storage 
device such as a tape drive. Later, you can use the RESTORE command 
(described later in this chapter) to retrieve these files and copy them 
to a named volume. 



X-667A 


INPUT PARAMETERS 

pathname Pathname of a file on the source volume. BACKUP 

saves all the files starting from this point on 
the file tree. If you specify the logical name of 
the device only, BACKUP saves all files in the 
volume, beginning with the root directory. If you 
specify a file and not a directory, then only the 
specified file is saved. 

DATE BACKUP saves all files created or modified on or 

after the date and time specified with the 
DATE/TIME parameters. If the DATE parameter is 
omitted, the date defaults to the current system 
date. If both date and time parameters are 
omitted (DATE/TIME) , then the date and time 
default to 1/1/78 and 00:00:00. 

mm/dd/yy Form used to specify the DATE. 

mm Numerical designation for the month. (For 

example: 1 represents January, 2 represents 

February, estc.). Must be a digit. 

dd Numerical designation for the day of the 
month. Value must be in digits. 

yy Designation for the year. You enter this 
as a two digit number, as follows: 
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PERMIT 


This command allows you to grant or revoke user access to files that you 
own. The format of this command is as follows: 



INPUT PARAMETERS 

pathname-list One or more pathnames, separated by commas, of the 

files that are to have their access rights or list 
of accessors changed. 

access Access characters that grant or rescind the 

corresponding access to the file, depending on the 
value parameter that follows. The possible values 
include: 

Value Access 

D Delete 

L or R List (for directories) and 

read (for data files) 

A Add entry (for directories) 

and append (for data files) 

C or U Change (for directories) and 

Update (for data files) 

N Rescinds all access not 

explicitly granted (used 
without an accompanying value) 

If specified without an accompanying value, each 
access character grants the specified access. 
Specifying N alone rescinds all 
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value 


user-list 


DATA 


DIRECTORY 


MAP 


access and removes the users specified with the 
USER parameter from the file's access list. 
Specifying N with other characters grants the 
access specified by those characters and rescinds 
all other access. You can use L and R 
interchangeably for both data files and 
directories; likewise C and U. 

Value which specifies whether to grant or rescind 
the associated access right. Possible values 
include : 

Value Meaning 

0 Resscind the access right 

1 Grant the access right 

The default value is 1. That is, specifying an 
access character without a value grants the 
corresponding acc€iss . 

User IDs for whom the previously-specified access 
rights apply. Two special values are also 
acceptable for this parameter. They are: 

WORLD Special user ID ( OFFFFh) giving all 
users access to the file. 

* Designator Indicating that the 

access rights apply to all users 

currently in the file's access list. 

The Operating System limits each file to three 
user IDs in the access list. If you omit this 
parameter, PERMIT assumes the user ID associated 
with your interactive job. 

Specifies that thei access information applies to 
the data files in the pathname list. If you omit 
both the DATA and DIRECTORY parameters , PERMIT 
assumes both. 

Specifies that the access information applies to 
the directories in the pathname list. If you omit 
both the DATA and DIRECTORY parameters, PERMIT 
assumes both. 

Specifies that access information also applies to 
the map and volume label files in the pathname 
list. If you use the MAP parameter, you must 
specify the full pathname of any map files or 
volume label files in the pathname list. For, 
example PERMIT :fO:R?* DLAU MAP will change the 
access rights for all map files and volume label 
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files on the volume (with the exception of R?SAVE 
which is unaffected by the MAP parameter). Notice 
that, in this instance, the Human Interface does 
not interpret the "?" as a wild card character. 

QUERY Causes PERMIT to prompt for permission to modify 

the access rights associated with each file. It 
does this prompting by displaying the following 
message: 

<pathname> , 

accessor = <new id> , <new access>, PERMIT? — 

Enter one of the following (followed by a carriage 
return) in response to the query: 

Entry Action 

Y or y Change the access. 

E or e Exit from the PERMIT command. 

R or r Change the access and continue 

with the command without 
further query. 

Any other Do not change access; continue 

character with PERMIT command and query 

for next access change, if any. 


DESCRIPTION 

You can use the PERMIT command to update* the access information for the 
following files: 

• Files for which you are listed as the owner. 

• Files for which you have change--entry access to the file’s parent 
directory. 

You cannot change the access information for other files. PERMIT can 
perform the following functions: 

• Adding or subtracting users from a file's list of accessors. 

This list determines which users have access to the file. 

• Setting the type of access (access rights) granted to the users 
in the accessor list. 

Currently the Operating System allows only three user IDs in the list of 
accessors, but one of these IDs can be the special ID WORLD, which grants 
access to all users. 
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You specify the type of access to be granted or rescinded by means of 
access characters and values. You can concatenate access characters and 
values together or you can separate the individual access specifications 
with commas. For example, if you want to grant delete access and rescind 
add and update access, you could enter any of the following combinations: 

AODUO 

A0,D,U0 

AODIUO 

A0,D1,U0 

As you can see from the previous lines, I) is equivalent to Dl. Also, the 
order in which you specify access characters is not important. 

If there are multiple occurrences of an access character in the PERMIT 
command, PERMIT uses the last such character to determine the access. 

For example, the combination: 

D0,A1,R1,D1 

is the same as the combination: 

A1,R1,D1 

In the first combination, the Dl overrides the DO. 

You can use the N character to rescind all access to the file. If 
specified alone, it removes user IDs from the accessor list. However, 
the N character can also be useful when changing access rights, if you 
don’t remember the specified user’s current access rights. In this case 
you can specify the N character first, to clear all the access rights, 
and follow it with other characters to grant the desired access. For 
example, if you want to grant list access only, you could specify "NL" 
instead of "DOAOCOL" . 

After changing the access information for a file, PERMIT displays the 
following information: 

<pathname> , 

accessor = <accessor ID>, <access> 


where <pathname> is the pathname of the specified file, <accessor ID> is 
the user ID of one of the files accessors, and <access> Indicates the 
access rights that the corresponding user has, PERMIT displays the 
access rights as access characters: DLAC for directories and DRAU for 
data files. If a particular access right is not allowed, the display 
replaces the corresponding character with a dash (-). For example, the 
display: 


-L-C 


indicates that the corresponding user has list and change access. 
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RESTOI 


• output specification missing 

You did not specify a pathname to indicate the destination of the 
restored files. 


• <pathname>, READ access required 

You do not have read access to a file on the backup volume; 
therefore RESTORE cannot restore the file. 


• <pathname>, too many input pathnames 

You attempted to enter a list of logical names for the backup 
devices. You can enter only one input logical name per 
invocation of RESTORE. 
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SUBMIT 


This command reads and executes a set of commands from a file in 
secondary storage instead of from the console keyboard. 



INPUT PARAMETERS 

pathname Name of the file from which the commands will be 

read. This file may contain nested SUBMIT 
commands . 

parameter-list Actual parameters that are to replace the formal 

parameters in the SUBMIT file. You must surround 
this parameter list with parentheses. You can 
specify as many as 10 parameters, separated by 
commas, in the SUBMIT command. If you omit a 
parameter, you must reserve its position by 
entering a comma. If a parameter contains a 
comma, space, or parenthesis, you must enclose the 
parameter in single quotes. The sum of all 
characters in the parameter list must not exceed 
512 characters. 


OUTPUT PARAMETERS 

TO Causes the output from each command in the SUBMIT 

file to be written to the specified new file 
instead of the console screen. If the output file 
already exists , the SUBMIT command displays the 
following message: 

<pathname>, already exists OVERWRITE? 
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Enter Y, y, R, or r if you wish the existing 
output file to be deleted. Enter any other 
character if you do not wish the existing file to 
be deleted. A response other than Y or y causes 
the SUBMIT command to be terminated and you will 
be prompted for a new command entry. 

OVER Causes the output for each command in the SUBMIT 

file to be written over the specified existing 
file instead of the console screen. 

AFTER Causes the output from each command in the SUBMIT 

file to be written to the end of an existing file 
instead of the console screen. 

out-pathname Pathname of the file to receive the processed 

output from each command executed from the SUBMIT 
file. If no preposition or output file is 
specified, TO :C0: is the default. 

ECHO ECHO causes the a copy of the data read from the 

first level of a SUBMIT file to be sent to the 
CRT,, This parameter lets you know which action 
specified within a SUBMIT file is currently 
executing. Nested SUBMIT commands do not have 
their contents sent to the console. 

DESCRIPTION 

To use the SUBMIT command you must first create a data file that defines 
the command sequence and formal parameters (if any). The Operating 
System first looks for the pathname ending in "CSD". If no such file is 
found, then the Operating System looks for the specified file in the 
pathname. 

Any program that reads its commands from the console input (:CI:) can be 
executed from a SUBMIT file. If another SUBMIT command is itself used in 
a SUBMIT file, it causes another SUBMIT file to be invoked. You can nest 
SUBMIT files to any level of nesting until memory is exhausted (each 
level of SUBMIT requires approximately lOK of dynamic memory). When one 
nested SUBMIT file completes execution, it returns control to the next 
higher level of SUBMIT file. 

If, during the execution of SUBMIT (or any nested SUBMIT), you enter the 
CTRL/ c character to abort processing, all SUBMIT processing exits and 
control returns to your user session. 

When you create a SUBMIT file, you indicate formal parameters by 
specifying the characters %n, where n ranges from 0 through 9. When 
SUBMIT executes the file, it replaces the formal parameters with the 
actual parameters listed in the SUBMIT command (the first parameter 
replaces all instances of %0, the second parameter replaces all Instances 
of %1, and so forth). If the actual parameter is surrounded by quotes, 
SUBMIT removes the quotes before performing the substitution. If there 
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is no actual parameter that corresponds to a formal parameter, SUBMIT 
replaces the formal parameter with a null string. 

When you specify a preposition and output file (other than :C0;) in a 
SUBMIT command, only your SUBMIT command entry will be echoed on the 
console screen; the individual command entries in the submit file are not 
displayed on the screen as they are loaded and executed. 

The SUBMIT command will display the following message when all commands 
in the submit file have been executed: 

END SUBMIT <pathname> 

You may use SUPER sub-commands (such as CHANGEID) within a SUBMIT file. 

To do so, you must include a SUPER command in the SUBMIT file. The SUPER 
command must precede any of the sub-commands in the file. When the 
SUBMIT file encounters the SUPER command, you are prompted for a 
password. Execution of the remainder of the file does not resume until 
you respond. You can avoid interrupting execution of the SUBMIT file by 
invoking the file while you are in the SUPER mode. In this case, the 
SUBMIT file still requires an embedded SUPER command. However, you are 
not prompted to re-enter the password when the SUBMIT file executes. 


ERROR MESSAGES 

• <pathname>, end of file reached before end of command 

The last command in the input file was not specified completely. 
For example, the last line might contain a continuation character 

• <parameter>, incorrectly formed parameter 

You separated the Individual parameters in the parameter list 
with a separator character other than a comma. 

• <pathname>, output file same as input file 

You attempted to place the output from SUBMIT into the input file 

• <pathname>, too many input files 

You specified more than one pathname as input to SUBMIT. SUBMIT 
can process only one file per invocation. 

• <parameter>, too many parameters 
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ZSCAN 


This command reads an object file or an object library and displays the 
Identification Number of all ZAPs that have been applied to that file. 


■( 



X-905 


INPUT PARAMETER 

input-path The pathname of the object file or object 

library to be scanned. The pathname 
cannot contain wildcard characters. The 
pathname must specify a file, not a 
directory . 


DESCRIPTION 

Fixes for problems discovered in the operation system software are 
distributed through the iRMX 86 Update Service. Intel refers to these 
fixes as "ZAPs". ZAPs are patched modules that replace the corresponding 
module in the operation system. 

Each update diskette contains an acctimulation of all ZAPs assured during 
the current release of the operating system. When you install the latest 
update, all ZAPs (from the current update and from previous updates) are 
automatically applied to your system. 

The ZSCAN command allows you to check which ZAPs have been applied to an 
object file or an object library. Beginning with iRMX 86, Release 6.0, 
Update 2.0 all ZAPs (including all ZAPs from previous Release 6 updates) 
are marked by a unique identifier string. Installing Update 2 — or any 
later update — assures that ZAP identifier strings are affixed to all 
ZAPs currently applied to iRMX 86 Release 6.0. ZSCAN finds occurrences 
of there strings and returns information about the associated ZAPs. 

When you invoke ZSCAN, you must specify an object file or an object 
library. You can not Invoke the command to find all of the ZAPs applied 
within a specified directory. Furthermore, you cannot use wildcard 
characters in the pathname of the file to be scanned. 

Output from ZSCAN is automatically directed to your terminal. To 
re-direct output to any other destination, place the ZSCAN command line 
in a SUBMIT file. Then invoke the SUBMIT file specifying the desired 
output destination. 
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By default, the IRMX 86 system object files are not accessible to user 
WORLD. Therefore, if you intend to use: ZSCAN on a bootable system object 
file, you must grant user WORLD read access rights to that file (using 
the Human Interface PERMIT command) or invoke ZSCAN from the SUPER mode. 


OUTPUT DISPLAY 

Upon successful execution, the ZSCAN command displays one of the two 
following messages. 

When ZSCAN encounters ZAPs : 


< filename > , has the following ZAP(s) applied: 

< zap id > , < class > : for iRMX 86 R6.0, < layer > < version > 


< zap id > , < class > : for iRMX 86 R6.0, < layer > < version > 


wher e ; 

<filename> the name of the file being scanned. 

<zap id> the identification code for the ZAP: 

Z BR A XX 
B_ 

where: 

BR = a iRMX 86 Release 6.0 ZAP; 

A = a Class A ZAP 

B = a Class B ZAP 

XX = a unique ID number from 0 to 99 


<class> the class of the ZAP. Class A indicates a 

supported ZAP distributed through the iRMX 86 
update service. Class B indicates an 
un-supported ZAP with limited distribution. 

<layer> the layer of the operating system (e.g. Nucleus, 

BIOS, etc.) that the ZAP pertains to. 

<version> the version of the operating system layer that 

the ZAP pertains to. 
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When ZSCAN encounters no ZAPs: 

< filename > , No ZAPs applied 
where: 

< filename > the name of the file bing scanned. 

ERROR MESSAGES 

• < filename > file does not exist. 

There is no file wJLth the pathname specified in the command. 

• < filename > is not an object module. 

The file specified in the command is not an object module and 
thus cannot be scanned for ZAPs. 
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<fnodenum>, fnode out of range The fnode number that you specified 

was larger than the largest fnode 
number in the volume. 

no badblocks file Your system does not have a bad 

blocks file. This message could 
appear because you used a Release 4 
or earlier version of the Human 
Interface command, FORMAT, when you 
formatted your disk. 
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DISK COMMAND 

This command displays the attributes of the volume being verified. You 
can abort this command by typing a CONTROL-C (press the CONTROL key, and 
while holding it down, press the C key). The format of the DISK command 
is as follows: 



x-225 

OUTPUT 

The output of the DISK command depends on whether the volume is formatted 
as a physical or named volume. For a physical volume, the DISK command 
displays the following information: 

Device name = <devname> 

Physical disk 

Device gran = <devgran> 

Block size = <devgran> 

No of blocks = <numblocks> 

Volume size = <size> 


where: 

<devname> Name of the device containing the volume. This is 

the physical name of the device, as specified in the 
ATTACHDEVICE Human Interface command. 

<devgran> Granularity of the device, as defined in the device 

unit information block (DUIB) for the device. Refer 
to the iRMX 86 CONFIGURATION GUIDE for more 
information about DUIBs. For physical devices, this 
is also the volume block size. 

<numblocks> Number of volume blocks in the volume. 

<size> Size of the volume, in bytes. 

For a named volume, the DISK command displays the following Information: 

Device name = <devname> 

Named disk. Volume name = <volname> 

Device gran = <devgran> 

Block size = <volgran> 

No of blocks = <numblocks> 

No of Free blocks = <numf reeblocks> 

Volume size = <size> 

Interleave = <inleave> 

Extension Size = <xsize> 

No of fnodes = <numfnodes> 

No of Free fnodes = <numf reef node s> 
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If the formatting program is unable to provide this 
information, it places an ASCII space in this field. 

• The next two bytes contain a two^igit ASCII 
sequence number which is incremented by the 
formatting program each time the formatting 
program changes in a way that affects the volume 
format. The Release 4 FORMAT Human Interface 
command places the characters "00" in this field. 

• The right-most three bytes of the field contain 
a three-digit ASCII number specifying the 
version of the Basic I/O System that was used in 
formatting the volume (for example, the 
characters "030" would indicate version 3.0). 

If the formatting program is unable to obtain 
this information, it places ASCII spaces in this 
field. 


DEVICE$SPECIAL(8) Reserved for special device-specific information. 

When no device-specific information exists, this 
field must contain zeros. If the device is a 
Winchester disk with an iSBC 215 controller or if 
the device is a disk with an iSBC 220 controller, 
the iRMX 86 Operating System imposes a structure on 
this field and supplies the following information: 


SPECIAL 

CYLINDERS 

FIXED 

REMOVABLE 

SECTORS 

SECTOR_SIZE 

ALTERNATES 


STRUCTURE ( 
WORD, 

BYTE , 

BYTE, 

BYTE , 

WORD, 

BYTE) ; 


where: 


CYLINDERS 

FIXED 

REMOVABLE 

SECTORS 

SECTOR_SIZE 

ALTERNATES 


Total number of cylinders on the 
drive . 

Number of heads on the fixed 
disk or Winchester disk. 

Number of heads on the removable 
disk cartridge. 

Number of sectors in a track. 

Sector size, in bytes. 

Number of alternate cylinders . 


The remainder of the Volume Label (bytes 430 through 511) is reserved and 
must be set to zero. 
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INITIAL FILES 


Any mechanism that formats IRMX 86 named volumes must place seven files 
on the volume during the format process. These seven files are the fnode 
file, the volume label file, the volume free space map file, the free 
fnodes map file, the bad blocks file, the root directory, and the space 
accounting file. The first of these files, the fnode file, contains 
information about all of the files on the volume. The general structure 
of the fnode file is discussed first. Then all of the files are 
discussed in terms of their fnode entries and their functions. 


FNODE FILE 

A data structure called a file descriptor node (or fnode) describes each 
file in a named file volume. All the Faodes for the entire volume are 
grouped together in a file called the f node file . When the I/O System 
accesses a file on a named volume, it examines the iRMX 86 Volume Label 
(described in the previous section) to determine the location of the 
fnode file, and then examines the appropriate fnode to determine the 
actual location of the file. 

When a volume is formatted, the fnode file contains seven allocated 
fnodes and any number of un-allocated fnodes. The original number of 
un-allocated fnodes depends on the FILES parameter of the FORMAT 
command. These allocated fnodes represent the fnode file, the volume 
label file, the volume free space map file, the free fnodes map file, the 
bad blocks file, the root directory, and the space accounting file. 

Later sections of this chapter describe these files. The size of the 
fnode file is determined by the number of fnodes that it contains. The 
number of fnodes in the fnode file also determines the number of files 
that can be created on the volume. The number of files is set when you 
format the storage medium. 

The structure of an individual fnode in a named file volume is as follows 
DECLARE 

FNODE STRUCTURE( 


FLAGS 

WORD, 

TYPE 

BYTE, 

GRAN 

BYTE, 

OWNER 

WORD, 

CR$TIME 

DWORD, 

ACCESS$TIME 

DWORD, 

MOD$TIME 

DWORD, 

TOTAL$SIZE 

DWORD, 

TOTAL $BLKS 

DWORD, 

POINTR(40) 

BYTE, 

THIS$SIZE 

DWORD, 

RESERVED$A 

WORD, 

RESERVE D$B 

WORD, 

ID$COUNT 

WORD, 

ACC(9) 

BYTE, 

PARENT 

WORD, 

AUX(*) 

BYTE) ; 
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DISKVERIFY command 1-2 
error messages 1-5 
output 1-4 

DISPLAYBYTE command 2-10 
DISPLAYDIRECTORY command 2-13 
DISPLAYFNODE command 2-15 
DISPLAYNEXTBLOCK command 2-20 
DISPLAYPREVIOUSBLOCK command 2-21 
DISPLAYWORD command 2-22 

example volume A- 2 2 
EXIT command 2-25 
file 

driver A-5 

granularity 2-15, A- 10 
owner 2-15, A- 11 
type 2-15, A-10 

fnode file A-8, A- 14 , A-24 

fnodes 2-15, A-5, A- 7 

FREE command 2-26 

free fnodes map 2-38, 2-39, A-15 

free space map 2-38, 2-39, A- 14 
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INDEX (continued) 


granularity 2-15, A-5, A-10 

HELP command 2-28 

initial files A-8 
input radices 2-2 
interleave factor A-3, A-5 
invoking 1-1 

iRMX 86 volume label A- 4 , A-23 
ISO information A-1 
ISO label A-2, A-22 


ke3Tword 2-1 

LIST option 2-47 
LISTBADBLOCKS command 2-29 
long files 2-15, A-9, A- 12, A- 18 

miscellaneous commands 2-30 
ADD 2-30 
ADDRESS 2-30 
BLOCK 2-31 
DEC 2-32 
DIV 2-32 
HEX 2-32 
MOD 2-33 
MUL 2-33 
SUB 2-34 

error messages 2-34 
examples 2-35 

named disk fields 2-9 
NAMED verification 1-3 
NAMED verification 2-47 
named volume structure A-1 
NAMED 1 verification 1-3 
NAMEDl verification 2-46 
output 2-48 
errors 2-51 

NAMED2 verification 1-3 
NAMED2 verification 2-47 
output 2-49 
errors 2-52 

notational conventions iii 

owner 2-15, A- 11 

parameters 2-1 
parent directory A- 13 
PHYSICAL verification 1-3 
PHYSICAL verification 2-47 
output 2-49 
errors 2-54 
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QUIT command 2-36 

railroad track schematic iii 
READ command 2-37 
reader level iii 
recording 

density A-4 
sides A-5 
size A-5 

related publications iv 
root directory A-5, A- 16 

SAVE command 2-38 

short files 2-15, A-9, A- 12, A- 17 

size A-5 

structure of iRMX 86 named volumes A-1 
SUBSTITUTEBYTE command 2-40 
SUBSTITUTEWORD command 2-43 
syntax iii 

track skew A- 6 

variable iii 
VERIFY command 1-3 
VERIFY command 2-46 


working buffer 2-37 
WRITE command 2-55 
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EXCEPTIONAL CONDITION MANAGEMENT 


• A reserved (WORD) parameter. 

• A (WORD) parameter containing the Numeric Processor Extension 
(NPX) status word. This parameter is valid only if the condition 
code is E$NDP$ERROR. 


ASSIGNING AN EXCEPTION HANDLER 

A task may use the SET$EXCEPTION$HANDLER system call to declare its own 
exception handler. Otherwise, the task inherits the exception handler of 
its job. A job can receive its own exception handler at the time of its 
creation. If it doesn’t, the job inherits the system exception handler. 
Thus, the Nucleus can always find an exception handler for the running 
task. 

A system exception handler is provided as part of the iRMX 86 Operating 
System. Depending on a configuration option, it either deletes or 
suspends any task on whose behalf it is invoked. The iRMX 86 
CONFIGURATION GUIDE describes this configuration option. 

Users wanting to write their own exception handlers should compile them 
under the PL/M-86 LARGE control, specifying the PUBLIC attribute. 

Any task can have the Debugger as its exception handler; see the 
description in Chapter 12 of the SET$EXCEPTION$HANDLER system call for 
instructions on how to dynamically make such an assignment. 

Alternatively, the Debugger or any other routine can be made the system 
exception handler statically; see the iRMX 86 CONFIGURATION GUIDE for 
information on how to do this. 


INVOKING AN EXCEPTION HANDLER 


An exception handler normally receives control when an exceptional 
condition occurs. However, when a task encounters an exceptional 
condition, it need not always have control passed to its exception 
handler. The factor that determines whether control passes to the 
exception handler is the task’s exception mode . This attribute has four 
possible values, each of which specifies the circumstances under which 
the exception handler is to get control in the event of an exceptional 
condition. These circumstances are: 

• Programmer errors only. 

• Environmental conditions only. 

• All exceptional conditions. 

• No exceptional conditions. 
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EXCEPTIONAL CONDITION MANAGEMENT 


When the Nucleus detects that a task has caused an exceptional condition 
in making a system call, it compares the type of the condition with the 
calling task’s exception mode. If a transfer of control is indicated, 
the Nucleus passes control to the exception handler on behalf of the 
task. The exception handler then deals with the problem, after which 
control returns to the task, unless the exception handler deleted the 
task. When the exception handler returns, the task can also detect that 
an error occurred, because the system call's except$ptr parameter points 
to a word containing the condition code. While the exception handler is 
executing, the errant task is still regarded by the Nucleus to be the 
running task. 

When a task is created, its exception mode is set to its job's default 
exception mode. The task can change its exception handler and exception 
mode attributes by using the SET$EXCEPTION$HANDLER system call. 


HANDLING EXCEPTIONS IN-LINE 


If a task's exception mode attribute does not direct the Nucleus to 
transfer control to the task's exception handler, the responsibility for 
dealing with an error falls upon the task. 

Each system call has as its last parameter a POINTER to a WORD. After a 
system call, the Nucleus returns the resulting condition code to this 
WORD. By checking this WORD after each system call, a task can ascertain 
whether the call was successful. (See Table 7-1 for condition codes.) 

If the call was not successful, the task can learn which exceptional 
condition it caused. This information can sometimes enable the task to 
recover. In other cases more information is needed. 

If a system call returns an exception code to indicate an unsuccessful 
call, all other output parameters of that system call are undefined. 


NOTE 

If an exceptional condition is caused 
by an invalid parameter, an exception 
handler, which is passed the parameter 
number of the first invalid parameter, 
should handle the condition. 


HANDLING EXCEPTIONS IN iAPX 286-BASED SYSTEMS 


The Operating System software catches and returns most of the exceptional 
conditions listed in Table 7-1. However, a few conditions (those noted 
with asterisks in the table) occur because the microprocessor catches (or 
traps) an invalid condition. 
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Figure 8-1, 


iAPX 86, 88 Interrupt Lines 
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INTERRUPT MANAGEMENT 


iAPX 286 Configurations 

An iAPX 286 environment is similar to an iAPX 86, 88 environment in all 
ways but one. If your iAPX 286-based system includes an 80287 NPX, you 
do not have to connect the NPX to a PIC, Instead of using the PIC, the 
NPX uses CPU interrupt traps 7 and 16 to communicate directly with the 
iAPX 286 component. This setup results in an extra Interrupt level for 
you to use any way you wish. Figure 8-2 illustrates this situation. 
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SEHD$UNI1 


/ 5% **********:*e:fe******:*f***tS:*i!:******!lfc*:*c***:*c* ****** t*T*****:fe ******* *:%***** 

* The calling task invokes the SEND$UNITS system call to send the * 

* units to the semaphore just created (sem$token.) * 

************************************************************************ ! 

CALL RQ$SEND$UNITS (sem$ token, 

three$unit s$sent , 

^status) ; 

• 

• Typical PL/M-86 Statements 


END SAMPLE PROCEDURE; 


CONDITION CODES 

E$OK No exceptional conditions. 

E$EXIST The semaphore parameter is not a token for an 

existing object. 

E$LIMIT The number of units that the calling task is trying 

to send would cause the semaphore’s supply of units 
to exceed its maximum allowable supply. 

E$NOT$CON- This system call is not part of the present 

FIGURED configuration. 

E$TYPE The semaphore parameter is a token for an object 

that is not a semaphore. 
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SET$EXCEPTION$ HANDLER 

SET$EXCEPTION$ HANDLER assigns an exception handler to the calling task. 


CALL RQ$SET$EXCEPTION$HANDLER (exception$inf o$ptr , except$ptr); 


INPUT PARAMETER 


I 


exception$info$ptr A POINTER to a structure of the following form: 


STRUCTURE( 

EXCEPTION$HANDLER$ OFFSET 
EXCEPTION$HANDLE R$BASE 
EXCEPTION$MODE 


WORD, 
SELECTOR , 
BYTE) ; 


where; 


exception$handler$offset contains the offset 
of the first instruction of the exception 
handler. 


exception$handler$base contains the base of 
the CPU segment containing the first 
instruction of the exception handler. 


exception$mode contains an encoded indication 
of the calling task’s intended exception 
mode. The value is interpreted as follows: 


When to Pass Control 
Value to Exception Handler 

0 Never 

1 On programmer errors only 

2 'On environmental conditions only 

3 On all exceptional conditions 


If exception$handler$off set and 
exception$handler$base both contain zeros , the 
exception handler of the calling task’s parent 
job is assigned. 


OUTPUT PARAMETER 

except$ptr A POINTER to a WORD to which the iRMX 86 

Operating System will return the condition code 
generated by this system call. 
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SIGNALS$EXCEPTIO 


SIGNAL$EXCEPTION 

The SIGNAL$EXCEPTION system call is invoked by OS extensions to signal 
the occurrence of an exceptional condition. 


CALL RQ$SIGNAL$EXCEPTION(exception$code , param$num, stack$pointer , 

reserved, npx$status$word , except$ptr) ; 


INPUT PARAMETERS 

exception$code A WORD containing the code (see list in Chapter 7) 
for the exceptional condition detected. 

param$num A BYTE containing the number of the parameter which 

caused the exceptional condition. If no parameter 
is at fault, param$num equals zero. 

stack$pointer A WORD which, if not zero, must contain the value 

of the stack pointer saved on entry to the 
operating system extension (see the entry procedure 
in Chapter 10 for an example). The top five words 
in the stack (where BP is at the top of the stack) 
must be as follows: 


FLAGS 

Saved by software interrupt 

CS 

to OS extension 

IP 


DS 

Saved by OS extension 

BP 

on entry 


Upon completion of SIGNAL$EXCEPTION, control is 
returned to either of two instructions. If 
stack$pointer contains a zero, control returns to 
the instruction following the call to 
SIGNAL$EXCEPTION. Otherwise, control returns to 
the instruction identified in CS and IP. 

reserved A WORD reserved for Intel use. Set this parameter 

to zero. 

npx$status$word A WORD containing the status of the NPX. 


OUTPUT PARAMETER 

except$ptr A POINTER to a WORD to which the iRMX 86 Operating 

System will return the condition code generated by 
this system call. 
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DESCRIPTION 

Operating system extensions use the SIGNAL$EXCEPTION system call to 
signal the occurrence of exceptional conditions. Depending on the 
exceptional condition and the calling task’s exception mode, control may 
or may not pass directly to the task’s exception handler. 

If the exception handler does not get control, the exceptional condition 
code is returned to the calling task. The task can then access the code 
by checking the contents of the word pointed to by the except$ptr 
parameter for its call (not for the call to SIGNAL$EXCEPTION) . 



EXAMPLE 

j ********:*?***************************** fc***5^*****:fe*:%5*f:V**** *****5%**:%****** 

* This example illustrates how the S I GNAL$ EXCEPT ION system call can * 

* be used to signal the occurrence of the exceptional condition * 

* E$CONTEXT. * 

•k'kiiit’k-k'k'kiiiiii'k'k'ii'kii'k'k'kiiit'k'k'k'k'k'k'k-k'k'k'k'k'k^'k'k-kk'kitii-k'k'k'k'k'k'k'k-k-k-k'k-k-k'k'k'k'kifk'k’k'k'k'k'k'k'k'k'k 


$INCLUDE(: FI: SAMPLE. EXT); /* Declares all system calls */ 


DECLARE e$context 
DECLARE param$num 
DECLARE stack$pointer 
DECLARE reserved$word 
DECLARE status 


LITERALLY 

BYTE; 

WORD; 

LITERALLY 

WORD; 


5H’ 


SAMPLE_PROCEDURE : 

PROCEDURE; 

param$num =0; /* no parameter at fault */ 

stack$pointer = 0; /* return control to instruction 

following call */ 

• 

• Typical PL/M-86 Statements 
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SIGNAL$INTERRUP 


EXAMPLE 


/************************************************************************ 

* This example illustrates how the SIGNAL$INTERRUPT system call can * 

* be used to activate an interrupt task. * 

$INCLUDE( : FI: SAMPLE. EXT) ; /* Declares all system calls */ 


DECLARE 

DECLARE 

DECLARE 

DECLARE 

DECLARE 

DECLARE 

DECLARE 

DECLARE 

DECLARE 


DECLARE 


the$first$word WORD; 

interrupt$level$7 LITERALLY ’0000 0000 0111 lOOOB’ ; 

/* specifies master Interrupt level 7 */ 
interrupt$task$f lag BYTE; 

interrupt $handler POINTER; 

data$segment WORD; 


status 

interrupt$s tatus 
ds$pointer 
PTR$ OVERLAY 


d s $po in t e r $o vl y 


WORD; 

WORD; 

POINTER; 

LITERALLY ’STRUCTURE (offset WORD, 

base WORD) ' ; 

/* establishes a structure for 
overlays */ 

PTR$OVERLAY AT (@ds$pointer) ; 

/* using the overlay structure, the 
base address of the interrupt 
handler’s data segment is 
identified */ 


INTERRUPT HANDLER: PROCEDURE INTERRUPT 59 PUBLIC; 


/* 59 is meaningless 
value. ENTER$ INTER- 
RUPT establishes 
actual level */ 


• Typical PL/M- 86 Statements 

• 

/ •kit-kitit-k'k-k^-kit'kifkitifkitifk-k'kifk’k'kifkifk-kitifk'k'kifk'k^ifkiiifk’kick'kii'k-k'kifkitifkifk-kic'kifk'kifkifk'kit 

* The calling interrupt handler invokes the ENTER$INTERRUPT system * 

* call which loads a base address value (defined by * 

* ds$pointer$ovly .base) into the data segment register. This * 

* register provides a mechanism for the interrupt handler to pass * 

* data to the interrupt task to be started up by the SIGNAL$INTERRUPT * 

* system call. * 

•k-k’k-k-k'k'kit'k-kit'k'k'k-k-k’k-kif-k-k'kit'kii'kic'k'kit-k-k-kit-k-k-kiiitii’k'k’kifk'k’k-kifkit'k-k'k'kit'k'k-k-kitififk'k'k'k'k'k'k'k'k j 

CALL RQ$ENTER$ INTERRUPT (interrupt$level$7, 

(ainterrupt$s tatus) ; 

CALL INLINE_ERROR_PROCESS (interrupt $status) ; 

• 

• Typical PL/M-86 Statements 
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ilGNAL$INTERRUPT 


I 


* The Interrupt handler uses SIGNAL$I1)JTERRUPT to start up its * 

* associated interrupt task. * 

**************************************5^*************************** ****** j 

CALL RQ$SIGNAL$ INTERRUPT (interrupt$level$ 7, 

@interrupt$status) ; 

CALL INLINE_ERROR_PROCESS (interrupt$status) ; 

END INTERRUPT_HANDLER; 

INLINE_ERROR_PROCESS : PROCEDURE ; 

IF interrupt$status <> E$OK THEN 
DO; 

• 

• In-line Error Processing PL/M-86 Statements 

END; 

END INLINE_ERROR_PROCESS; 

SAMPLE_PROCEDURE : 

PROCEDURE ; 

ds$pointer = @the$f irst$word; /* a dummy identifier used to point to 

interrupt handler’s data segment */ 
data$segment = ds$pointer$ovly .base; 

/* identifies the base address of the 
Interrupt handler's data segment */ 
interrupt $handler = INTERRUPT$PTR (INTERRUPTJIANDLER) ; 

/* points to the first instruction of 
th€* interrupt handler */ 

interrupt$task$flag = OlH; /* indicates that calling task is to be 

interrupt task */ 

• 

• Typical PL/M-86 Statements 


/************** ************:fc:fc:fc:t;:fc**:fc^^:^:fcV;* ************************** ****** 

* By first invoking the SET$INTERRUPT system call, the calling task * 

* sets up an interrupt level and becomes the interrupted task for * 

* level 7. * 

************************************************************************ j 

CALL RQ$SET$INTERRUPT (lnterrupt$level$7, 

lnterrupt$task$f lag, 
interrupt $handler , 
data$segment , 

^status) ; 

• Typical PL/M-86 Statements 
END SAMPLE PROCEDURE; 
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A$PHYSICAL$DETACH$DEVI( 


Note that , whether you specify a hard detach or not , there will be no 
attached files on the device after the device is detached. 


CONDITION CODES 

A$PHYSICAL$DETACH$DEVICE can return condition codes at two different 
times. The code returned to the callings task immediately after 
invocation of the system call is considered a sequential code. A code 
returned as a result of asynchronous processing is a concurrent exception 
code. A complete explanation of sequential and concurrent parts of 
system calls is in Chapter 7 of this manual. 

The following list is divided into two parts — one for sequential codes 
and one for concurrent codes. 


Sequential Condition Codes 

The Basic I/O System can return the following exception codes to the word 
specified by the except$ptr parameter of this system call. 

E$OK No exceptional conditions. 

E$EXIST One or more of the following parameters is not a 

token for an existing object: 

• The connection parameter 

• The resp$mbox parameter 

E$LIMIT The calling task^s job has already reached its 

object limit. 

E$MEM The memory available to the calling task's job is 

not sufficient to complete the call. 

E$NOT$CONFIGURED This system call is not part of the present 

configuration. 

E$NOT$DEVICE$CONN The specified connection parameter is not a device 

connection. 

E$SUPPORT The specified connection was not created by this 

job. 

E$TYPE At least one of the following is true: 

• The connection parameter is a token for an 
object that is not a connection. 

• The resp$mbox parameter is a token for an 
object that is not a mailbox. 
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Concurrent Exception Codes 

The Basic I/O System will return the following codes in an I/O result 
segment at the mailbox specified by resp$mbox. After examining the 
segment, you should delete it. 

E$OK No exceptional conditions . 

E$FNEXIST The device specified by the connection parameter 

is already being detached. 

E$IO An I/O error occurred during the operation, but 

the operation was successful an3rway. 

E$OUTSTANDING$- The call attempted a soft detach, but connections 
CONNS to the device still existed. 
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in$baud$rate 


out$baud$rate 


REPLACE 


Bits Value and Meaning 

0 = Coordinates increase from left to 

right . 

1 = Coordinates decrease from left to 

right. 

12 Vertical axis orientation control 

(corresponds to OSC characters T:F), 

This specifies whether the coordinates on 
the terminal’s vertical axis increase or 
decrease as you move from top to bottom 
across the screen, 

0 = Coordinates increase from top to 

bottom. 

1 = Coordinates decrease from top to 

bottom. 

13-15 Reserved bits. For future compatibility, 

set to 0. 


NOTE 

If bits 4-5 contain 2 or 3, and bits 
6-8 also contain 2 or 3, then they must 
both contain the same value. That is, 
they must both reflect the same parity 
convention (even or odd). 


The input baud rate indicator (corresponds to OSC 
characters T:I), If you attempt to set this field 
to zero, the Basic I/O System ignores your entry 
and leaves the field set to its previous value. 

The word is encoded as follows: 

0 = Invalid. 

1 = Perform an automatic baud rate search. 

Other = Actual input baud rate, such as 9600. 

The output baud rate indicator (corresponds to OSC 
characters T:0). If you attempt to set this field 
to zero, the Basic I/O System ignores your entry 
and leaves the field set to its previous value. 

The word is encoded as follows; 

0 = Invalid. 

1 = Use the input baud rate for output, 

BIOS 8-99 UPDATE 2, 12/84 
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other = Actual output baud rate, such as 9600, 

Most applications require the input and output 
baud rates to be equal. In such cases, use 
in$baud$rate to set the baud rate and specify a 
one for out$baud$rate. 

scroll$lines An operator at a terminal can enter a control 

character (default is Control-W) when he/she is 
ready for data to appear on the terminal’s display 
screen. The scroll$lines value (corresponding to 
OSC characters T:15) specifies the maximum number 
of lines that are to be sent to the terminal each 
time the operator enters the control character. 

If you attempt to set this field to zero, the 
Basic I/O System Ignores your entry and leaves the 
field set to its previous value, 

x$y$size The low-order byte of this word specifies the 

number of character positions on each line of the 
terminal’s screen (and corresponds to OSC 
characters T:X), The high-order byte specifies 
the number of lines on the terminal’s screen (and 
corresponds to OSC characters T:Y), 

x$y$offset The ' low-order bytci of this word specifies the 

value that starts the numbering sequence of both 
the X and Y axes (and corresponds to OSC 
characters T;U). The high-order byte specifies 
the value to which the numbering of the axes must 
"fall back" after reaching 127 (and corresponds to 
OSC characters T:V), 

The remaining fields apply only for intelligent communications boards 
(such as the iSBC 544 board) that maintain their own input and output 
buffers separately from the ones managed by the Basic I/O System’s 
Terminal Support Code, If you aren’t sure whether you can set these 
fields, invoke A$SPECIAL with function code 4 to get the terminal 
attributes. If bit 15 of the flow$control field (the next one described) 
is set, your board is a buffered device and you can set the following 
fields, (If your board is not a buffered device, setting any of the 
following fields will cause the terminal support code to return an 
E$PAEAM Condition Code,) 

flow$control Specifies whether the communications board sends 

flow control characters (selected by the 
fc$on$char and fc$off$char fields, but usually XON 
and XOFF) to turn input on and off (corresponds to 
the OSC characters. T:G), The low^order bit (bit 
0) controls this option, as follows: 

0 Disable flow control, 

1 Enable flow control. 
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DELCLARE read$f ile$mark STRUCTURE( 

search BYTE) ; 

where: 

search A value indicating the direction of the search, as 

follows: 

00 Search forward 

OFFH Search backward (for start/stop drives 
only) 

When your task issues the A$SPECIAL system call with spec$func set to 9, 
the tape drive writes a file mark at the current position on the tape. 
This function also terminates tape write operations. 

When your task issues the A$SPECIAL system call with spec$func set to 10, 
the tape drive fast-forwards the tape to the end and then rewinds it to 
the load point. 


CONDITION CODES 

A$SPECIAL return condition codes at two different times. The code 
returned to the calling task immediately after invocation of the system 
call is considered a sequential condition code. A code returned as a 
result of asynchronous processing is a concurrent condition code. A 
complete explanation of sequential and concurrent parts of system calls 
is in Chapter 7 of this manual. 

The following list is divided into two parts — one for sequential codes, 
and one for concurrent codes . 


Sequential Condition Codes 

The Basic I/O System can return the following condition codes to the word 
specified by the except$ptr parameter of this system call. 

E$0K No exceptional conditions. 

E$BUFFERED$CONN The connection parameter is a connection produced 

by the Extended I/O System. You cannot use it 
with Basic I/O System calls. 

E$EXIST At least one of the following is true: 

• One or more of the following parameters or 
fields is not a token for an existing object: 
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- The connection parameter 


E$IFDR 

E$LIMIT 

E$MEM 

E$NOT$CONFIGURED 

E$PARAM 


E$ SUPPORT 


- The resp$mbox parameter 

- The mailbox field in the notify structure. 
(Spec$func « 2.) 

- The object field in the notify structure. 
(Spec$func == 2.) 

- The semaphore field in the signal$pair 
structure. (Spec$func =6.) 

• The connection is being deleted. 

The function requested (spec$func) is not valid 
for the type of file specified by the connection 
parameter. 

The calling task's job has already reached its 
object limit. 

The memory available to the calling task's job is 
not sufficient to complete the call. 

This system call is not part of the present 
configuration. 

At least one of the following is true: 

• The spec$func parameter was 5, and one or more 
of the following is true: 

- Bits 0-1 of the connection$f lags field was 
equal to 0. 

- Bits 6-8 of the terminal$f lags field was 
greater than 4. 

• The spec$func parameter was 6, and the 
character field was greater than IFH. 

• The spec$func parameter was greater than 10. 

• One or more of the fields related to buffered 
devices (high$water$mark, low$water$mark , 
fc$on$char, fc$off$char) was set while bit 15 
of the flow$control field was reset to zero 
(specifying an un-buff ered device). 

The specified connection was not created by this 
job. 
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One or more of the following parameters or fields 
is a token for an existing object of the wrong 
type: 


• The connection parameter, 

• The resp$mbox parameter. 

• The mailbox field of the notify structure, 
(Spec$func = 2.) 

• The semaphore field of the signal$pair 
structure. (Spec$func = 6.) 


Concurrent Condition Codes 

The Basic I/O System can return the following condition codes in an I/O 
result segment at the mailbox specified by resp$mbox. After examining 
the segment, you should delete it. 


E$0K 

No exceptional conditions . 

E$C0NN$N0T$0PEN 

The specified connection is not open. This 
applies only to stream and physical files. 

E$ FLUSHING 

The specified connection was closed before the 
function could be completed. 

E$IDDR 

The specified function is not supported by the 
device containing the file. 

E$IFDR 

The connection reifers to a named file, but the 
function is not "notify". 

E$I0 

An I/O error occurred which might have prevented 
the operation from completing. Examine the 
unit$status field of the I/O result segment for 
more information. 


E$NOT$DEVICE$CONN The function code, is ’notify' , but the specified 

connection is not a device connection. This 
applies only to named and physical files. 

E$SPACE One of the following is true: 

• This call attempted to format a track of a 
physical file that is beyond the end of the 
volume . 

• 'Ihis call attempted to format a track of a RAM 
disk other than track 0. 
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E$STREAM$ SPECIAL One of the following is true: 

• This is a "query" request, but another query is 
already queued, This applies only to stream 
files . 

• This is a "satisfy" request, but either a query 
request is queued, or no requests are queued. 
This applies only to stream files. (See 
Artificially Satisfying a Stream File I/O 
Request in the DESCRIPTION.) 
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MODES THAT A TERMINAL INHERITS FROM A COMECTION 

This section describes the modes that depend on the connection to the 
terminal, rather than on the terminal itself. With these modes, when 
multiple connections to a terminal exist, the terminal might operate one 
way when communicating via the first connection and a different way when 
communicating via the second connection. 

Each of these modes relates directly to one or more bits in the 
connection$f lags word for the connection (as defined in the Chapter 8 
description of the A$SPECIAL system call). The names of the modes, the 
single-letter identification codes for the modes, the bits of the 
connection$flags word to which they correspond, and a brief description 
of their functions are given in Table F-2. 

Assuming that the OSC control mode is set appropriately, the modes that a 
terminal inherits from a connection can be altered. The syntax of an OSC 
sequence that will change one or more of these modes is as follows: 



where; 


0997 


C: Indicates that this sequence applies to a 

connection. The Terminal Support Code ignores all 
but the first letter, so you can supply any group 
of characters that begins with "C". However, you 
must Include the colon (:) at the end. 

mode id An ID letter from the list of modes given in 

Table F-2. 

decimal number The value to which you want to set the mode. This 

number must be of the character data type. 


Table F-2 contains a brief description of the modes and values. For a 
more complete description, refer to the description of A$SPECIAL in 
Chapter 8. 
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C$SEND$CO$RESPONSE 


C$SEND$CO$RESPONSI 


C$SEND$CO$RESPONSE , a message processing call, sends a message to :C0: 
and reads a response from :CI:. 


CALL RO$C$SEND$CO$RESPONSE(response$p , response$max, message$p, 

except $ptr) ; 


INPUT PARAMETERS 

message$p A POINTER to a STRING containing the message to be 

sent to :C0:. If zero, no message is sent. 

response$max A WORD whose value specifies the length in bytes of 

the string pointed to by the response$p parameter. 
The value in response$max must equal the length of 
the string plus one (stringlength +1). If 
response$max is zero or one, no response from :CI: 
will be requested; control returns to the calling 
task immediately . 


OUTPUT PARAMETERS 

response$p A POINTER to a STRING that receives the operator’s 

response from :CI:. 

except$ptr A POINTER to a WORD in which the Human Interface 

returns a condition code. 


DESCRIPTION 

When used with all its features, C$SEND$CO$RESPONSE sends the string 
pointed to by message$p to :C0; and waits for a response from :CI:. It 
places this response in the string pointed to by response$p. However, If 
message$p is zero, C$SEND$CO$RESPONSE omits sending the message to :C0:; 
if either response$max or response$p is zero, it does not wait for a 
response from :CI:. Therefore, the operations performed by 
C$SEND$CO$RESPONSE depend on the values of the message$p and response$max 
parameters, as follows: 

message$p response$max Action 

zero zero Perform no I/O 

zero non-zero Send no message, wait for input 

non-zero non-zero Send message, wait for input 

non-zero zero Send message, don’t wait 
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If C$SEND$CO$RESPONSE requests a response from :CI:, output from other 
tasks can be displayed at :C0; while the system waits for a response from 
;CI: . 

The main distinction between C$SEND$CO$RHSPONSE and C$SEND$EO$ RESPONSE 
calls is that C$SEND$EO$RESPONSE always sends messages to and receives 
messages from the operator’s terminal; input and output cannot be 
redirected to another device. In contrast, C$SEND$CO$RESPONSE sends 
messages to :C0; and receives messages from :CI:; therefore, programs 
such as SUBMIT can redirect this input and output. 


EXCEPTION CODES 

E$OK No exceptional conditions were encountered. 

E$CONTEXT The calling task’s job was not created by the Human 

Interface. 


E$CONNECTION$- At least one of the following is true: 
OPEN 


E$EXIST 

E$FLUSHING 

E$IO$HARD 

E$IO$OPRINT 


• The connection to :CI: was not open for reading 
or the connection to :C0: was not open for 
writing. 

• The connection to :CI: or :C0: was not open. 

• The connection to :CI: or :C0: was opened with 
A$OPEN rather than S$OPEN. 

The token value for :CI: or :C0: is not a token for 
an existing object,. 

The device containing the :CI; and :C0: files was 
being detached. 

While attempting to access the :CI: or :C0: file, 
the Operating Syste;m detected a hard I/O error. 

While attempting to access the :CI: or :C0: file, 
this call found that the device was off-line. 
Operator intervention is required. 
C$FORMAT$EXCEPTION returns the value E$IO$NOT$READY 
for this code. 
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E$IO$SOFT 

E$IO$UNCLASS 

E$IO$WRPROT 

E$LIMIT 


E$MEM 

E$NOT$ CONNECTION 

E$PARAM 
E$ SPACE 

E$STREAM$ SPECIAL 

E$SUPPORT 

E$TIME 

REPLACE 


While attempting to access the :CI: or :C0: file, 
this call detected a soft I/O error. It tried 
again, but was unsuccessful. Another try might be 
successful. 

An unknown type of I/O error occurred while this 
call tried to access the :CI: or :C0: file. 

While attempting to obtain a connection to the :C0: 
file, this call found that the volume containing 
the file is write-protected. 

At least one of the following is true: 

• The calling task's job has already reached its 
object limit. 

• The calling task's job, or the job's default 
user object, is already involved in 255 
(decimal) I/O operations. 

• The calling task's job was not created by the 
Human Interface. 

The memory available to the calling task's job is 
not sufficient to complete the call. 

The call obtained a token for an object that should 
have been a connection to :CI: or :C0: but was not 
a file connection. 

The call attempted to write beyond the end of a 
physical file. 

One of the following is true: 

• The output volimie is full. 

• The call attempted to write beyond the end of a 
physical file. 

When attempting to read or write to :CI: or :C0:, 
the. Extended I/O System issued an invalid stream 
file request. 

The connection to :CI: or :C0: was not created by 
this job. 

The calling task's job was not created by the Human 
Interface. 
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C$SEND$EO$RESPONSE 


C$SEND$EO$RESPONSE , a message processing call, sends a message to and 
reads a response from the operator's terminal. 


CALL RQ$C$SEND$EO$RESPONSE(response$p , response$max, message$p, 

except $ptr) ; 


INPUT PARAMETERS 

message$p A POINTER to a STRING containing the message to be 

sent to the operator's terminal. If zero, no 
message is sent, 

response$max A WORD whose value specifies the length in bytes of 

the string pointed to by the response$p parameter. 
The value in response$max must equal the length of 
the string plus one (stringlength +1). If 
response$max is zero or one, no response from the 
operator's terminal will be requested; control 
returns to the calling task Immediately. 

OUTPUT PARAMETERS 

response$p A POINTER to a STRING that receives the operator's 

response from the terminal. 

except$ptr A POINTER to a WORD in which the Human Interface 

returns a condition code. 


DESCRIPTION 

When used with all its features, C$SENDJ?EO$RESPONSE sends the string 
pointed to by message$p to the operator's terminal and waits for a 
response from the operator. It places this response in the string 
pointed to by response$p. However, if message$p is zero, 
C$SEND$EO$RESPONSE omits sending the message to the operator; if either 
response$max or response$p is zero, it does not wait for a response. 
Therefore, the operations performed by C$SEND$EO$RESPONSE depend on the 
values of the message$p and response$max parameters, as follows: 

message$p response$max Action 

zero zero Perform no I/O 

zero non-zero Send no message, wait for input 

non-zero non-zero S!end message, wait for input 

non-zero zero Send message, don't wait 
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DQ$RENAME 


The DQ$RENAME system call changes the pathname of a file. 


CALL DQ$RENAME (path$ptr, new$path$ptr , except$ptr); 


INPUT PARAMETERS 

path$ptr A POINTER to a STRING that specifies the pathname 

for the file to be renamed. 

new$path$ptr A POINTER to a STRING that specifies the new 

pathname for the file. This path must not refer 
to an existing file. 


OUTPUT PARAMETER 

except$ptr A POINTER to a WORD where the system places the 

condition code. Condition codes are described in 
Appendix B. 


DESCRIPTION 

This system call allows your programs to change the pathname of a data 
file or a directory. Be aware that when you rename a directory, you are 
changing the pathnames of all files contained in the directory. When you 
rename a file to which a connection exists — this is permitted — the 
connection to the renamed file remains established. 

A file’s pathname may be changed in any way, provided that the file or 
directory remains on the same volume. 
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DQ$RESERVE$ IO$MEMORY 


The DQ$RESERVE$IO$MEMORY lets your program reserve enough memory to 
ensure that it can open and attach the files it will be using. 


CALL DQ$RESERVE$IO$MEMORY (number$f iles , number$buf fers , except$ptr) ; 


I 


INPUT PARAMETERS 

number$files A WORD whose value indicates the maximum number of 

files the program will have attached 
simultaneously. This value must not be greater 
than 12. Moreover, no more than 6 of these files 
may be open simultaneously. 

number$buffers A WORD whose value indicates the total number of 

buffers (up to a maximum of 12) that will be 
needed at one time. For example, if your program 
will have two files open at the same time, and 
each of them has two buffers (specified when they 
are opened), number$files should be two and 
number$buffers four. 


OUTPUT PARAMETER 

except$ptr A POINTER to a WORD where the system places the 

condition code. Condition codes are described in 
Appendix B. 


DESCRIPTION 

DQ$RESERVE$IO$MEMORY sets aside memory on behalf of the calling program, 
guaranteeing that it will be available when needed later for attaching 
and opening files. This memory is used for internal UDI data structures 
when the program requests file connections via DQ$ATTACH and for buffers 
when the program opens file connections via DQ$OPEN. Memory reserved in 
this way is not eligible to be allocated by DQ$ALLOCATE. Your program 
should call DQ$RESERVE$IO$MEMORY before making any calls to DQ$ALLOCATE. 

In the call to DQ$RESERVE$IO$MEMORY, you may specify as many as 12 files 
(that can be attached using the reserved memory) and as many as 12 
buffers (that can be requested when opening files). 


REPLACE 


UDI 2-42 


UPDATE 2, 12/84 



WRITING A CUSTOM DEVICE DRIVER 


The format of the call to the Finish I/O procedure is as follows: 
CALL finish$io(duib$p , ddata$t); 


where: 

finish$io Name of the Finish I/O procedure. You can specify 

any name for this procedure as long as it does not 
conflict with other procedure names. You must, 
however, provide its starting address in the DUIBs 
of all device-units that it services, 

duib$p POINTER to the DUIB of the device-unit of the 

device being detached. The finish$io procedure 
needs this DUIB in order to determine the device 
on which to perform the final processing, 

ddata$t SELECTOR containing the location of the data 

storage area originally created by the init$io 
procedure. The finish$io procedure must delete 
this resource and any others created by driver 
routines . 


QUEUE I/O PROCEDURE 

The I/O System calls the Queue I/O procedure to place an I/O request on a 
queue, so that it can be processed when the device is not busy. The 
Queue I/O procedure must actually start the processing of the next I/O 
request on the queue if the device is not busy. The format of the call 
to the Queue I/O procedure is as follows: 

CALL queue$io(iors$t , duib$p , ddata$t); 
where: 

queue$io Name of the Queue I/O procedure. You can use any 

name for this procedure as long as it does not 
conflict with other procedure names. You must, 
however, provide its starting address for the 
DUIBs of all device-units that it services, 

iors$t SELECTOR containing the location of an lORS, This 

lORS describes the request. When the request is 
processed, the driver (though not necessarily the 
queue$io procedure) must fill in the status fields 
and send the lORS to the response mailbox 
(exchange) indicated in the lORS, Chapter 2 
describes the format of the lORS, It lists the 
information that the 1/ 0 System supplies when it 
passes the lORS to the queue $io procedure and 
indicates the fields of the lORS that the device 
driver must fill in. 
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duib$p POINTER to the DUIB of the device-unit for which 

the request is intended. 

ddata$t SELECTOR containing the location of the data 

storage area originally created by the init$io 
procedure. The queue$io procedure can place any 
necessary information in this area in order to 
update the request queue or status fields. 


CANCEL I/O PROCEDURE 

The I/O System can call the Cancel I/O procedure in order to cancel one 
or more previously queued I/O requests. The iRMX 88 I/O System does not 
call Cancel I/O, but in the IRMX 86 environment Cancel I/O is called 
under either of the following two conditions: 

• If the user makes an RQ$A$PHYSICAL$DETACH$ DEVICE system call and 
specifies the hard detach option (refer to the iRMX 86 BASIC I/O 
SYSTEM REFERENCE MANUAL for a description of this call) . This 
system call forcibly detaches all objects associated with a 
device-unit . 

• If the job containing the task which made an I/O request is 
deleted. The I/O System calls the Cancel I/O procedure to remove 
any requests that tasks in the deleted job might have made. 

• If the user deletes a connection to a device. The I/O system 
calls Cancel I/O to remove any I/O requests pending for that 
device. 

If the device cannot guarantee that a request will be finished within a 
fixed amount of time (such as waiting for input from a terminal 
keyboard), the Cancel I/O procedure must actually stop the device from 
processing the request. If the device guarantees that all requests 
finish in an acceptable amount of time, the Cancel I/O procedure does not 
have to stop the device itself, but only removes requests from the queue. 

The format of the call to the Cancel I/O procedure is as follows: 

CALL cancel$io(cancel$id , dulb$p, ddata$t); 
where: 

cancel$id Name of the Cancel I/O procedure. You can use any 

name for this procedure as long as it doesn't 
conflict with other procedure names. You must, 
however, provide its starting address in the DUIBs 
of all device-units that it services. 

cancel$id WORD containing the id value for the I/O requests 

that are are to be cancelled. Any pending 
requests with this value in the cancel$id field of 
their lORS's must be removed from the queue of 
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requests by the Cancel I/O procedure. Moreover, 
the I/O System places a CLOSE request with the 
same cancel $id value in the queue. The CLOSE 
request must not be processed until all other 
requests with that cancel$id value have been 
returned to the I/O System. 

duib$p POINTER to the DUIB of the device-unit for which 

the request cancellation is intended. 

ddata$t SELECTOR containing the location of the data 

storage area originally created by the init$io 
procedure. This area may contain the request 
queue. 


IMPLEMENTING A REQUEST QUEUE 

Making I/O requests via system calls and the actual processing of these 
requests by I/O devices are asynchronous activities. When a device is 
processing one request, many more can be accumulating. Unless the device 
driver has a mechanism for placing I/O requests on a queue of some sort, 
these requests will become lost. The common and random access device 
drivers form this queue by creating a doubly linked list. The list is 
used by the QUEUE$IO and CANCEL$IO procedures, as well as by 
INTERRUPT$TASK. 

Using this mechanism of the doubly linked list, common and random access 
device drivers implement a FIFO queue for I/O requests. If you are 
writing a custom device driver, you might want to take advantage of the 
LINK$FOR and LINK$BACK fields that are provided in the lORS and implement 
a scheme similar to the following for queuing I/O requests. 

Each time a user makes an I/O request , the I/O System passes an lORS for 
this request to the device driver, in particular to the Queue I/O 
procedure of the device driver. The common and random access driver 
Queue I/O procedures make use of the LINK$FOR and LINK$BACK fields of the 
lORS to link this lORS together with lORSs for other requests that have 
not yet been processed. 

This queue is set up in the following manner. The device driver routine 
that is actually sending data to the controller accesses the first lORS 
on the queue. The LINK$FOR field in this lORS points to the next lORS on 
the queue. The LINK$FOR field in the second lORS points to the third 
lORS on the queue, and so forth until, in the last lORS on the queue, the 
LINK$FOR field points back to the first lORS on the queue. The LINK$BACK 
fields operate in the same manner. The LINK$BACK field of the last lORS 
on the queue points to the previous lORS. The LINK$BACK field of the 
second to last lORS points to the third to last lORS on the queue, and so 
forth, until, in the first lORS on the queue, the LINK$BACK field points 
back to the last lORS in the queue. A queue of this sort is Illustrated 
in Figure 6-1. 
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The device driver can add or remove requests from the queue by adjusting 
LINK$FOR and LINK$BACK pointers in the lORSs . 


Second lORS 



x-679 


Figure 6-1. Requeist Queue 


To handle the dual problems of locating the queue and ascertaining 
whether the queue is empty, you can use a variable such as head$queue. 
If the queue is empty, head$queue contains the value 0. Otherwise, 
head$queue contains the address of the first lORS in the queue. 


irk-k 
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TIMER ROUTINES 


$subtitle( ’ Initialize Time’) 

/:%*** ***********************************************************:%* ******** 
init time 


This procedure zeros the timer, creates a task to 
maintain the timer, and a region to ensure exclusive 
access to the timer. This procedure must be called 
before the first time that get_time or set_time is 
called. Also, this procedure should be called only 
once. The easiest way to make sure this happens is to 
call init_time from your Initialization task. 

The timer task will run in the job from which this 
procedure is called. 

If your application experiences £i lot of interrupts, 
the timer may run slow. You can rectify this 
problem by raising the priority of the timer 
task. To do this, change the 128 in the 
rq$create$task system call to a sjmaller number. 

This change may slow the processing of your 
interrupts , 


************************************************************************* / 


init time: PROCEDURE(ret status p) REEOTRANT PUBLIC; 


POINTER, 

BASED ret_status_p WORD, 
TASK, 

WORD; 

time in sec = 0; 


DECLARE ret_status_p 
ret_s tatus 
t ime r_task_t 
local status 


time_region = rq$create$region 

(PRIORITY QUEUE, 


/* Create a region, */ 
ret status p); 


IF (ret_status <> E$0K) THEN 

RETURN; /* Return with error. */ 


data_seg_p = @data_seg_p; /* Get contents of 

DS register, */ 


timer task t = rq$create$task 

/* 

Create timer task. 

*/ 

(128, 

/* 

priority 

*/ 

^maintain time. 

/* 

start addr 

*/ 

data seg p o.base. 

/* 

data seg base 

*/ 

0, 

/* 

stack ptr 

*/ 

512, 

/* 

stack size 

*/ 

0, 

/* 

task flags 

*/ 


ret status p); 


REPLACE 


Programming Tcichniques 3-7 


UPDATE 2, 12/84 



TIMER ROUTINES 


IF (retjstatus <> E$0K) THEN 
CALL rq$delete$region 

(time region, @local status); 


/* Since could not */ 
/* create task, */ 
/* must delete */ 
/* region. */ 


END init_time; 
END timer; 
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CHAPTER 3 

PROGRAMMING CONSIDERATIONS 


The iRMX 86 Terminal Handler supports terminal input and output by 
providing mailbox interfaces. Figure 3-1 shows the use of these 
mailboxes. In the figure, an arrow pointing from a task to a mailbox 
represents an RQ$SEND$MESSAGE system call. An arrow pointing from a 
mailbox to a task Indicates an RQ$RECEIVE$MESSAGE system call. 


PROVIDED 
BY USER 


PROVIDED 
BY USER 



x-601 


Figure 3-1. Input and Output Mailbox Interfaces 


The protocol that tasks observe is much the same for input and output. 
In each case, the task initiates I/O by sending a request message to a 
mailbox. An input request mailbox (default name RQTHNORMIN) and an 
output request mailbox (default name ROTHNORMOUT) are provided. These 
mailboxes are cataloged in the root job directory. In the case of 
multiple terminals, one input and one output mailbox will be cataloged 
for each Terminal Handler. (See Chapter 4 for more information about 
multiple versions of the Terminal Handler.) Figure 3-2 illustrates the 
protocol for finding the root job token and for obtaining the input and 
output mailbox tokens. 
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PROGRAMMING CONSIDERATIONS 


/ *********************ife5<f**:fc*:<c ife******?fe*:*( ***:%******* ***:)lf****:fe**:fc***:fc******* 

* This example Illustrates the protocol for finding the root job token * 

* and for obtaining the input and output mailbox tokens. * 


DECLARE rtjb$token 

WORD; 

DECLARE root$j ob 

LITERALLY '3'; 

DECLARE status 

WORD; 

DECLARE input$mbx$ token 

WORD; 

DECLARE wait$forever 

LITERALLY 'OFFFFH'; 


/*By setting the input parameter to three, the GET$TASK$TOKEN primitive 
will return the root job's TOKEN.*/ 

rtjb$token = RQ$GET$TASK$TOKENS (root$job, 

(tistatus); 

/*The following LOOKUP$OBJECT primitives use the default mailbox names.*/ 


input$mbx$ token = RQ$LOOKUP$OBJECT 


(rt jb$token, 

@(10, 'RQTHNORMIN' ), 
wait$forever , 
@!status) ; 


output $mbx$token = RQ$L00KUP$0BJECT 


(rtjb$token, 

@!(11, 'RQTHNORMOUT' ), 
wait$forever , 

^status) ; 


Figure 3-2. Protocol for Obtaining: Root Job and Mailbox Tokens 


Refer to the iRMX 86 NUCLEUS REFERENCE MANUAL for more information 
concerning the individual primitives used in the previous example. When 
a task sends a message to the Terminal Handler mailbox, the Terminal 
Handler processes the request and then sends a response message back to 
the requesting task. The task waits at a response mailbox for the 
message. Thus, whether a task does input or output, it first sends and 
then receives. The full details of the input and output protocols are 
described later in this chapter. Output is discussed first because it is 
somewhat easier to understand. 

For both input and output, a task sends a message segment to the Terminal 
Handler. The format of a request message is depicted in Figure 3-2. The 
numbers in that figure are offsets, in bytes, from the beginning of the 
segment. The field names have different meanings for input and for 
output. For both input and output, the first four fields are WORD 
values. The MESSAGE CONTENT field can be up to 132 bytes in length for 
input and up to 65527 bytes in length for output. 
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CONFIGURATION 


BSl.CSD *-*-* 

Generate the iAPX 86, 88 Bootstrap Loader V5.0 first stage. 


Invocation: submit bsl(first stage location, second stage location) 


run 

9 

asm86 

asm86 

asm86 

asm86 

asm86 

asm86 

asm86 

asm86 

asm86 

asm86 

asm86 


fl:bsl.a86 macro(90) 
fl:bserr.a86 macro(50) 
fl:b204.a86 macro(50) 
fl:b206.a86 macro(50) 
fl:b208.a86 macro(50) 
fl:b215.a86 macro(50) 
fl:b218a.a86 macro(50) 
fl:b251.a86 macro(50) 
fl:b254.a86 macro(50) 
fl:bsasi,a86 macro(50) 
fl:bscsi.a86 macro(50) 


object( : f 1 :bsl .obj ) 
object( :f 1 :bserr,obj ) 
object( :f 1 :b204,obj ) 
object( :f l:b206.obj ) 
object( ;f 1 ;b208.obj ) 
object( : f 1 :b215.obj ) 
object( :f 1 :b218.obj ) 
obj ect( :f 1 ;b251.obj ) 
object( :f 1 :b254.obj ) 
object( :f 1 ;bsasi,obj ) 
object( : f 1 :bscsi .obj ) 


print ( :fl:bs 1.1st) 
print ( :f 1 :bserr .1st) 
print( :f 1 :b204.1st) 
print( : f 1 :b206.1st) 
print ( : fl :b2 08.1st) 
print ( :fl;b215.1st) 
print ( :fl:b218.1st) 
print ( ; f 1 :b25 1.1st) 
print ( :f 1 :b254.1st) 
print ( :f 1 rbsasi.lst) 
print ( :f 1 rbscsi.lst) 


1 ink8 6 


:f 1 :bsl .obj , 

:f l:bserr.obj , 

& :f 1 rbcico.obj , 

; f 1 :b204.obj , 

:f 1 :b206.obj , 

: f 1 :b208.obj , 

:fl:b215.obj, 

; f 1 :b218.obj , 

:fl:b251.obj , 

: f 1 :b254.obj , 

:f 1 :bsasi.obj , 

:f 1 :bscsi .obj , 

:fl:bsl.lib 

to :fl:bsl.lnk print( :f Irbsl.mpl) 
nopublics except( f ir st~s tage , boot 


& 

St 

& ;for stand-alone serial channel 
& ;support 
& 

& 

& 

St 

St 

& 

St 

St 

St 

St 

St 

186, bootstrap entry) 


loc86 :fl:bsl.lnk & 

addresses(classes(code(%0),stack(%D) ) & 

order(classes(code,code_error, stack, data, boot) ) & 

noinitcode & 

start(f irst-stage) & 

& ; change above line to start(boot_186) if iAPX_186_INIT is invoked 

segsize(boot( 1 800H) ) & 

map print( :f l:bsl .mp2) & 

; Add "bootstrap" to loc86 when locating the first stage in ROM 


& 


Figure 2-2. First Stage Configuration File BSl.CSD 
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CONFIGURATION 


y 

exit 

y 

; Bootstrap Loader first stage generation complete. 


Figure 2-2. First Stage Configuration File BSl.CSD (continued) 


counter base port The 16-bit address of the base port used by the 

baud rate timer. This port varies according to 
the type of the device and, if applicable, the 
channel used on the device, as follows: 


8253 

8254 
80130 
80186 

82530 Channel A 
82530 Channel B 


Counter 0 Count Register Port 
Counter 0 Count Register Port 
ICWl Register Port 
Use OFFOOH on all Intel boards 
Channel A Command Register Port 
Channel B Command Register Port 


counter_port_delta The number of bytes between consecutive ports 

used by the timer. 

baud_counter The baud rate-generating counter on the timer. 

The devices and the counters you can specify for 
them are as follows: 


8253 

0, 

1, and 

2 

8254 

0, 

1 , and 

2 

80130 

2 



80186 

0, 

1 


82530 

0 




count A value that, whem loaded into the timer 

register, generates the desired baud rate. The 
method of calculating this value is described in 
the paragraphs following these parameter 
definitions . 

flags A value that, whe;n present, specifies which 

channel of an 82530 Serial Communications 
Controller will sserve as your serial controller. 
If you give any value except 82530 for the 
serlal_type parameter, omit this parameter; that 
is, write the macro as if the count parameter is 
the last parameter. If you give 82530 as the 
value of the serlal_type parameter, specify A 
(for Channel A) or B (for Channel B) for this 
parameter. 
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SPECIFIC MODIFICATIONS TO INDIVIDUAL INTEL CONTROLLER BOARDS 


Table 6-4. 

MUT.TIBUS® 

Priority 

Selection Jumpers (continued) 

Intel Board 

Remove 

Jumper 

Add 

Jumper 

Dejscription /Function 

iSBC 254S 



Default setting selects serial 
priority . 


E130-131 


Selects parallel priority. 

iSBX 270 



Not applicable. 

iSBX 351 



Not applicable. 

iSBC 534 



Not applicable. 

iSBC 544 



Not applicable. 


5 1/ 4-INCH DRIVE SELECTION JUMPERS 

Table 6-5 lists the jumpers you must change to incorporate a 5 1/ 4-inch 
flexible diskette into your system. 


Table 6-5. 5 1/4-Inch Drive Selection Jumpers 


Intel Board 

Remove 

Jumper 

Add 

Jumper 

Description/Function 

iSBC 204 



Use of 5 1/4 -inch diskette 
drives controlled by the 
iSBC 204 is not supported 
by iRMX 86. 

iSBC 206 



Not applicable. 

iSBC 208 

E18-E19 

E4-E5 
E6-E11 
El 7 -El 9 

Selects 5 1/4-inch drives. 
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SPECIFIC MODIFICATIONS TO INDIVIDUAL INTEL CONTROLLER BOARDS 


Table 6-5. 5 1/4-Inch Drive Selection Jumpers (continued) 



Remove 

Add 


Intel Board 

Jumpe r 

Jumper 

Description /Function 

iSBC 208 

E21-E22 

EI7-E22 

Install only if using 

(continued) 



double sided 5 1/4-inch 
diskette drives that do 
not supply a double-sided 
signal. 

iSBC 215 



Intel recommends that you 
use the iSBC 215G for 
controlling 5 1/4-inch 
winchester drives. 

iSBC 215G 

Wl, 1-2 

Wl, 1-3 

Selects 5 1/4-inch 


W2, 1-2 


CMI, model 5412, 


W5, 1-2 

W5, 1-3 

winchester drives. 


W6, 1-2 

W6, 1-3 



W7, 1-2 

W7, 1-3 



W8, 1-2 

W8, 1-3 
W9, 1-2 



W13, 1-3 

W13, 1-2 



W14, 1-3 

W14, 1-2 



W15, 1-2 
W16, 1-3 

W16, 1-2 



W22, 1-3 

W22, 1-2 
W27, 1-2 



W33, 1-3 

W33, 1-2 



W34, 1-2 

W37, 1-2 



W35, 1-2 

W38, 1-2 


iSBX 218 



Use of 5 1/ 4-inch diskette 
drives controlled by the 
iSBC 218 is not supported 
by iRMX 86. 

iSBX 218A 



Default configuration 
selects 5 1/ 4-inch 
diskette drives . 

iSBC 220 



Not applicable. 

iSBX 251 



Not applicable. 
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SPECIFIC MODIFICATIONS TO INDIVIDUAL INTEL CONTROLLER BOARDS 


Table 6-7. Controller Board Switch Settings (continued) 


Intel Board 

Switch Setting 

Description/Function 

iSBC 220 

SI, 

1-7 

OFF 

Selects port address lOOH, 

(DIP switches) 


8 

ON 



S2, 

1-2 

ON 

Selects a 16-bit bus and 
16-bit address decoding. 



3-10 

OFF 

Selects port address lOOH. 

iSBC 220 

E16 

- E15 


Selects port address lOOH 

(Wire Wraps) 

E18 

- E17 


Selects a 16-bit bus and 


E20 

- E19 


16-bit address decoding 

iSBX 251 


Not applicable. 

iSBC 254 


Not applicable. 

iSBC 254S 


Not applicable. 

iSBX 270 


Not applicable. 

iSBX 351 


Not applicable. 

iSBC 534 


Not applicable. 

iSBC 544 




If your board does not 
have a switch SWl, then 
refer to Table 6-3, 


SWl, 

1-4 

ON 

Selects Dual-Port RAM 
address. Also refer to 
Table 6-4, 


SWl, 

5 

ON 

Selects Dual-Port RAM 
size of 16K. 


SWl, 

6 

OFF 



SWl, 

7 

ON 

Selects 2132k EPROMS. 


SWl, 

8 

OFF 

Configures board for slave 
mode. 
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SPECIFIC MODIFICATIONS TO INDIVIDUAL INTEL CONTROLLER BOARDS 


DIP HEADER CONFIGURATIONS FOR THE RS232C PROTOCOL 

Table 6-8 lists the DIP-header configurations you need to supply to 
implement the RS232C serial protocol. This configuration process 
involves either soldering wires on a solder style header or inserting 
wires into a pin-and -socket style header. 


Table 6-8. DIP Header Configurations for the RS232C Protocol 


Intel Board 

DIP Header 
Jumpers 

Description/Function 

iSBX 351 

3-13 

Board RxD to Terminal TxD. 


4-14 

Board TxD to Terminal RxD. 


7-8 

Board DSR to Board DTR. 


5-6 

Board RTS to Board CTS. 


11-12 

Terminal RTS to Terminal CTS . 


9-10 

Terminal DSR to Terminal DTR. 

iSBC 534 

4-5 

Board DSR to Board DTR. 


6-7 

Board RTS to Board CTS. 


8-10 

Board RxD to Terminal TxD. 


9-11 

Board TxD to Terminal RxD. 


12-13 

Terminal RTS to Terminal CTS . 


14-15 

Terminal DSR to Terminal DTR. 

iSBC 544 

2-3 

Board DSR to Board DTR. 


4-5 

Board RTS to Board CTS. 


6-12 

Board RxD to Terminal TxD. 


7-13 

Board TxD to Terminal RxD. 


14-15 

Terminal RTS to Terminal CTS . 


16-17 

Terminal DSR to Terminal DTR. 

Notes: Signal Names: 


TxD: Transmit Data 

RxD: Receive Data 

DTR: Data Terminal Ready 

DSR: Data Set Ready 

RTS: Request To Send 

CTS: Clear To Send 


MISCELLANEOUS JUMPERS 

Table 6-9 lists jumpering information not covered in the previous 
sections. The list of jumpers change different functional areas. 
Perform the changes to use default values established by Intel. 
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SOFTWARE INSTALLATION 


FIRST-TIME INSTALLATION OF THE OPERATING SYSTEM 

This section details the steps that you must take to install the iRMX 86 
Operating System. Before you begin, make certain that you know which Intel 
microprocessor runs your system; the installation procedure is changes 
slightly depending on the processor in your system. If at any time you see an 
error massage, stop the installation procedure and correct the problem. 


CAUTnON 


THE INSTALLATION PROCEDURE DESCRIBED 
HERE AUTOMATICALLY RE-FORMATS THE 
WINCHESTER DISK DRIVE. Therefore, back 
up any files you wish to save before 
you begin the installation procedure. 


STEP 1: RUNNING THE SYSTEM CONFIDENCE TEST (SCT) 

If you are using your own custom iRMX 86 development system, you should now 
turn on the power to your system. If you have built an iAPX 86-based 
development system, you will see a series of asterisks. If you have built an 
iAPX 286-based development system, you will see no display. In either case 
you should then type in an uppercase "U". Typing in an uppercase "U" 
initializes the Monitor and causes it to sign-on. Once you see the monitor 
prompt — a period — go to Step 2. 

If you are using a System 300 product, turn on the power for your system. In 
about 5 seconds you will see a display. If you have a System 86/300 Series 
microcomputer, the display will be a series of asterisks. If you have a System 
286/300 Series microcomputer, the display will be a single asterisk. In 
either case, type in an uppercase "U". This will cause the System Confidence 
Test (SCT) to execute. The SCT is only provided on System 300 Series 
Microcomputers . 

After you type in an uppercase "U", you will see on the CRT display status 
reports from the SCT. For specific information on the meaning of the reports 
consult the SYSTEM 86/300 SERIES DIAGNOSTIC MAINTENANCE MANUAL or the SYSTEM 
286/300 SERIES DIAGNOSTIC MAINTENANCE MANUAL. 

Shortly after beginning the display on systems based on the iAPX 86 
microprocessor, the SCT on System 86/300 products requests you to enter an 
uppercase ”1" in response to the "PIC" test. At this point you have three 
opjtions: 1) do nothing; 2) type in an uppercase "I"; or 3) press the front 

panel interrupt button. On a system with an un-formatted Winchester disk, all 
three actions have the same result — ^you exit the SCT and enter the monitor. 

The system should respond by displaying: 

*BREAK* at <xxxx:yyyy> 


The period (".") is the monitor prompt, and <xxxx:yyyy> is the address where 
the entry into the monitor occurred. At this point you are ready to go on to 
the next step. 
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SOFTWARE INSTALLATION 


Once the execution of the SCT on a System 286/300 product begins, the 
terminal requests you to enter a response to the 8274 MPSC test. After 
displaying the test prompt, the SCT waits for your response. Respond 
with a period (".") if you want to enter the monitor at the end of the 
execution of the SCT rather than boot the iRMX 86 system. If you do not 
enter a period within six seconds, the test times out and responds with 
the message "Chb Interrupt Timeout". Normally in the enhanced mode, you 
may enter any character at the 8274 MPSC prompt and the bootstrap loader 
boots the operating system after the SCT executes. However, when 
installing the Operating System, you need to return to the monitor after 
running the SCT. Entering a period at the 8274 MPSC test prompt signals 
the SCT to do this. The system should respond by displaying: 

*BREAK* at <xxxx:yyyy> 


The period (".") is the monitor prompt., and <xxxx:yyyy> is the address 
where the entry into the monitor occurred. At this point you are ready 
to go on to the next step. 


NOTE 

If you are installing the Release 6 
version of the Operating System on 
hardware that is already running the 
Release 5 version of the iRMX 86 
Operating System , do not let the SCT 
run to completion. When the SCT 
requests that you input the uppercase 
"I", you must press the front panel 
Interrupt button. If you do not press 
the interrupt button, you won^t enter 
the monitor. 


STEP 2: INSTALLING THE FIRST DISKETTE 

Place the diskette with the label INSTALLATION DISKETTE in the flexible 
diskette drive. If you have a system based on the iAPX 86 
microprocessor, place the diskette with the label IRMX 86 INSTALLATION 
DISKETTE FOR iAPX 86-BASED SYSTEMS into the flexible diskette drive. If 
you have a system based on the iAPX 286 microprocessor, place the 
diskette with the label iRMX 86 INSTALLATION DISKETTE FOR iAPX 286-BASED 
SYSTEMS into the flexible diskette drive. 
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SOFTWARE INSTALLATION 


Enter the following monitor command depending on the hardware in your 
system: 


HARDWARE IN YOUR SYSTEM 


ENTER 


iSBC 218A Board mounted on 

any iSBC 215 that controls either 

a 5 1/4 or 8-Inch Flexible Disk Drive . b :wfO: 

iSBX 208 Controller ,b :af0: 

If you have any SYSTEM 300 Series Microcomputer, use the command b :wf0: . 

The Monitor command boots the file '*/system/rmx8 6" from the INSTALLATION 
DISKETTE so that the INSTALLATION DISKETTE is the system device. The 
INSTALLATION DISKETTE only contains those Human Interface commands 
required to initiate the installation process. 

Upon completion of the bootstrap load process, the terminal displays the 
following message: 

iRMX 86 HI CLI, Vx.y: USER= 65535 
Copyright <years> Intel Corporation 

Next, the system prompts you for the correct date and time. You may 
enter the date in any one of the following three formats: 

month/date/year (11/29/1984) 
date month year (29 NOV 1984) 
date month year (29 NOVEMBER 1984) 

After you have entered the date, the system echoes the information and 
prompts you for the time. Enter the time in the format 
HOURS : MINUTES: SECONDS , You may omit the minutes and seconds fields if 
you desire; the system sets them to zero. When you have completed 
entering the time, the system responds by echoing the entered time. 

After the date and time are entered and echoed, the system displays the 
line: 

END SUBMIT : PR0G:R?L0G0N 


STEP 3: BECOME THE SYSTEM MANAGER 

To continue the installation process, you need to gain access to the 
system manager privileges. Enter the command SUPER to gain the power of 
system manager. In response to the password prompt, enter in a carriage 
return. The system responds with the prompt "SUPER-". You now have 
access to the system manager privileges and you may continue with the 
installation process. 
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STEP 4: INSTALLING IRMX™ 86 FILES ON A WINCHESTER DISK 

During this phase of the installation process you will be formatting your 
Winchester drive and copying the iRMX 86 files from the Installation 
Diskette to your formatted Winchester disk. Only those files necessary 
for booting the operating system from your Winchester disk are copied at 
this time. To install these essential files, enter the command: 

SUBMIT /INSTAL( device name, Interleave, files) 


"Device name" is the physical name of the device that boots the operating 
system after installation (this device is also known as the system 
device). Refer to Table 10-1 for the correct device names. Do not use 
the generic name for the device. You must use the name corresponding to 
the actual device. For exan^)le, if you have an 8 -inch 30MB Priam 
Winchester in your system, you must use the device name "IwO" or "iwl". 

"Interleave" is "4" for 5 1/4-inch Winchesters and "3" for 8 -inch 
Winchesters . 

"Files" is the number of files you want to be able to create on your 
Winchester disk. A number between 3000 and 6000 should be selected. 

This number is dependant on your application. Generally, if you have a 
1(MB or 15MB Winchester drive, create 3000 files. If you have a larger 
Winchester drive, create 4000 files. If you have purchased the source 
code from Intel for the iRMX 86 Operating System, you must specify 
exactly 5000 files. 


Table 10-1. Start-Up System Device Names of Winchester Drives 


Device 

Device Name 

CMI 5 1/4" 10 MB Winchester 
(formatted) 

cmO , cml 

CMI 5 1/4" 15 MB Winchester 
(formatted) 

cmbO, cmbl 

Quantum 5 1/4" 40MB Winchester 
(un -formatted ) 

qmaO, qmal 

8" 3CMB Priam Winchester 
(formatted) 

iwO, iwl 

8" 70MB Priam Winichester 
(un -format ted) 

iwbO, iwbl 
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SOFTWARE INSTALLATION 


STEP 5; BOOTING THE OPERATING SYSTEM FROM A WINCHESTER DISK 

After the system has executed the submit command described in Step 4, the 
Winchester disk contains enough iRMX files to boot the Operating System 
and to use selected Human Interface comittands. However, before you can 
boot the Operating System from the Winchester disk, you must remove the 
INSTALLATION DISKETTE and reset the system. Reset the system by pressing 
the front panel RESET button or by whatever means you have designed into 
the system. 

If you have a System 300 Series Microcomputer, you will see the display 
described in Step 1 in about 6 seconds. This time do not type an 
uppercase "U" in response to the asterisk(s). After about 12 seconds, 
the SCT will time out and the Terse mode of the SCT will execute. Allow 
the SCT to run (this verifies that all your hardware is operating 
correctly). After the SCT successfully executes, the bootstrap loader 
automatically boots the iRMX 86 Operating System that you copied to the 
Winchester disk in Step 4. 

If you are using a custom built IRMX 86 development system, you must type 
in an uppercase "U" in response to the Monitor’s display described in 
Step 1. You will then see the Monitor’s prompt At this point, 

type "b" to boot the iRMX 86 Operating System that you copied to the 
Winchester disk in Step 4. 

Once the operating system loads, the system again prompts you for the 
date and time. Enter the correct date and time according to the 
Instructions given in Step 2. 

To complete the Operating System installation, you need privileges of the 
system manager. Enter the SUPER command; the system prompts you for the 
correct password. In response to the password prompt, enter a carriage 
return. The system responds with the prompt "super-". Now you have the 
privileges of the system manager and may complete the iRMX 86 Operating 
System installation. 


STEP 6: INSTALLING THE REMAINING iRMX™ 86 FILES 

Now that you have successfully booted the operating system from the 
Winchester disk, install the iRMX 86 files from the remaining seven 
iRMX 86 Operating System diskettes. 


CAUTHON 


If you are using a system equipped with 5 1/4-inch 
flexible diskette drives, YOU MUST REMEMBER TO 
PERFORM THE FOLLOWING STEPS FOR EACH DISKETTE USED: 

(1) Insert the diskette into the diskette drive. 

(2) Attach the device using the ATTACHDEVICE command. 

(3) Use the diskette. 

(4) Detach the device using the DETACHDEVICE command. 

(5) Remove the diskette from the diskette drive. 
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You must detach and re-attach the 5 l/4--inch flexible diskette drives 
with each diskette installation because the I/O System cannot detect the 
"door open" condition and does not know when the I/O System buffers 
contain invalid data from a previous diskette. You do not need to detach 
and re-attach the device for each 8-inch diskette installation, 

A, Before installing the remaining iRMX! files, you must "attach" the 
flexible diskette drive to the system by using the following command: 

super- ATTACHDEVICE device name AS ; logical name; 

The physical name of the flexible diskette drive is "device name" and 
":logical name:" is the name the system uses to address the flexible 
diskette drive. Attach a 5 1/4 -inch diskette drive in a System 300 
Series Microcomputer using the command: 

super- ATTACHDEVICE wmfdxO AS ;fd0: 

Attach an 8-inch flexible diskette drive in a System 300 Series 
Microcomputer using the command: 

super- ATTACHDEVICE wfdO AS :fd0 : 

B, To copy the remaining iRMX 86 files from diskettes number 1 through 7 
(listed in Table 1-2), insert the next diskette into the flexible 
diskette drive and enter the following command: 

super- SUBMIT :logical name: INST AL( ; logical name:) 

Both logical names in the preceding SUBMIT command are the same; the 
system uses these names to address the device as specified in the 
preceding ATTACHDEVICE command (typically :fd0:). Each diskette has 
a file named INSTAL,CSD which, when executed, will copy the contents 
of that diskette into the correct directory on the Winchester disk, 

C, Remember, if you have 5 1/4-inch flexible disk drives, you must 
detach the device using the DETACHDEVICE command. The DETACHDEVICE 
command has the syntax "DETACHDEVICE :logical name:". 

Repeat steps A through C for all of the remaining Release Diskettes, 

As the SUBMIT command installs the Operating System files, a series of 
messages appear. If the system encounters an error during the process, 
it displays an error message but does not stop: the system continues 
executing the SUBMIT command until it reaches the end of the process. 
Watch these messages and be alert for error messages. When the system 
displays an error message, stop the system and correct the fault. 
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STEP 7: INSTALLING THE LANGUAGE UTILITIES 

The next step is to install the language utilities. If you do not have a 
System 300 Series Microcomputer from Intel, you must purchase the 
language products in addition to the IRMX 86 Operating System. 

At this point you must still have system manager privileges. (You must 
still be in SUPER.) 

Detach the flexible disk drive before installing the Language Utilities. 
To do this, use the DETACHDEVICE command. 

Before beginning the installation of the language utilities, check that 
you have the proper diskettes. You should have the following diskettes: 

• IRMX 860 ASM86 AND NUMERICS LIBRARIES 

• IRMX 860 UTILITIES PACKAGE 

• IRMX 863 PL/M-86 

The order that you install the diskettes is important. You must install 
the diskettes in the order they are presented in the list above. 

First, place the diskette with the label IRMX 860 ASM86 AND NUMERICS 
LIBRARIES into the flexible disk drive. Enter in the following SUBMIT 
command to install the diskette: 

SUBMIT /CONFIG/CMD/INSTAL860( <devicename>) 


<devicename> is the physical device name for the flexible disk drive. 
The device name for 8-lnch diskettes is wfdO and the device name for 
5 1/4-inch diskettes is v/mfdxO. Note, the device name is not a logical 
name so it does not have colons surrounding it. 

Second, take out the first diskette (iRMX 860 ASMS 6 AND NUMERICS 
LIBRARIES) and place into the flexible disk drive the diskette with the 
label IRMX 860 UTILITIES PACKAGE. Next, enter in the following SUBMIT 
command to install the diskette: 

SUBMIT /CONFIG/CMD/INSTAL860u( <devicename> ) 


<devicename> is the physical device name for the flexible disk drive. 

Third, take the second diskette (iRMX 860 UTILITIES PACKAGE) out of the 
disk drive and place into the drive the diskette with the label IRMX 863 
PL/M-86. Next, enter in the following SUBMIT command to install the last 
diskette: 

S UBMIT /CONFIG/ CMP/ INSTAL863( <devicename> ) 


<devicename> is the physical device name for the flexible disk drive. 
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STEP 8: INSTALLING THE UPDATE PACKAGE 

The final phase of installing the iRMX 86 Operating System is the 
installation of the current iRMX 86 Release 6 update package. You must 
perform this step even if you are installing a new system. Applying the 
update package is Intel's mechanism for fixing problems identified in the 
current version of the software. Failure; to apply the update results in 
the installation of an un-fixed version of the iRMX 86 Operating System. 

The update package accompanies all shipm€;nts of the iRMX 86 Operating 
System. (The update package is shipped in a separate box.) Each update 
package contains one or more update diskettes, one or more shrinkwrapped 
packets of documentation change pages, a customer letter, and an update 
installation guide. (Occasionally, additional documentation may be 
supplied in response to special circumstances.) 

The Update Diskettes contain all of the fixes (ZAP's) that are to be 
applied to the iRMX 86 Operating System. The diskettes are labelled: 

"RMX86W Rx.y UP z" 


where: w is the media type (E>, E, or J) , 

is the release level of the Operating System, 

^ is the revision level of the Operating System, 

^ is the release level of the Update Package. 

The update Installation guide contains both detailed descriptions of each 
ZAP and detailed instructions on installing the Update Package. 

To install the Update to your system, find the Update Package and follow 
the instructions in the update installation guide. 


REFERRING TO OTHER MANUALS BEFORE RUNNING YOUR SYSTEM 

Once you have completed the eight steps listed in the previous section 
you are ready to use your iRMX 86 Operating System. Refer to the 
following manuals for additional help: 

• For basic information about your system and the manuals in your 
Release 6 documentation set , refer to the INTRODUCTION TO THE 
iRMX 86 OPERATING SYSTEM. 

• For information about memory partition sizes and further insights 
into your Start-up System (including information on how to 
generate a custom Operating Syst€;m) , refer to the iRMX 86 
CONFIGURATION GUIDE. 
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FILES CONTAINED ON THE RELEASE DISKETTES 


4) Bootstrap Loader 

Other 
boot .060 
b204.a86 
b206.a86 
b208.a86 
b215.a86 
b2 1 8a . a8 6 
t)251.a86 
b254.a86 
bsasi .a86 
bscsi ,a86 
bcico.obj 
bsl ,a86 
bserr ,a86 
bcsdm.a86 
bsl ,csd 
bsl,mp2 
bsl 


5) System Debugger 


Libraries Includes Other 

sdb.llb sdb.030 

DISKETTE 4: iRMX 86 HUMAN INTERFACE COMMANDS 

1) instal.csd 



had.r86 

hatach.r86 

hback.r86 

hcopy .r86 

hcrdir .r86 

hdate ,r86 

hdcopy ,r86 

hdd.r86 

hdeb.r86 

hdelet .r86 

hdir .r86 

hdtach ,r86 

hform.r86 

histat .r86 

hjobdl.r86 

hlocdt .r86 

block, r8 6 

hlogs ,r86 

hmem.r86 

hpath.r86 

hprmt ,r86 

hrest .r86 

hr name ,r86 

hsbmt ,r86 

hsuper.r86 

htime.r86 

hucopy ,r86 

hvers .r86 

hdvfy ,r86 

hwhoam.r86 

hupcpy .csd 

hi. 030 



Libraries Includes 

bsl, lib bsl.inc 

b204,inc 
b206.inc 
b208,inc 
b215.inc 
b218a.inc 
b251.inc 
b254.inc 
bsasi .inc 
bscsi .inc 
bsldev.inc 
bserr .inc 
bclco.inc 
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DISKETTE 5; iRMX 86 ICU (part 1 of 2), FILES UTILITY AND PATCH UTILITY 

1) instal.csd 

2) ICU (Part 1 of 2) 

icu86.020 

icu86.86 

rmx86.def 

3) Files Utility 

files. 041 
files 
files .Ink 
floc.csd 
f s86.def 
f sl86.def 

4) Patch Utility 

ptch86 .023 
ptch86 .86 
patch .csd 
patch .cmd 
patch. a86 


DISKETTE 6; iRMX 86 ICU (Part 2 of 2), UDI AND CRASH ANALYZER DISKETTE 

1) instal.csd 

2) ICU 

icu86.020 
icu86 .862 
icu86.hlp 
rmx286 .def 


3) UDI 


Libraries 
udi .lib 

Includes 

Other 
udi .030 

4) Crash Analyzer 

Libraries 
sdumpr .lib 

Includes 

Other 

scr s86.01 1 
scrs86.86 
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DISKETTE 7: IRMX 86 Include Files, Interface Libraries and ICU System 
Definition Files 


1) instal.csd 


2) All the iRf-IX 86 Interface Libraries are on this diskette. 


rpif c.lib 
ipif c.lib 
epif c.lib 
Ipifc.lib 
hpif c.lib 
compac.lib 

3) All the IRm. 


rpif 1, lib 
ipif 1. lib 
epif 1, lib 
Ipifl.lib 
hpifl.lib 
large. lib 

86 exception code 


small. lib 
literal files are 


on this diskette. 


nexcep.lit Idwptr.lit 

iexcep.lit Itksel.lit 

eexcep.lit Itkwrd.lit 

lexcep .lit 
hexcep .lit 
uexcep .lit 

4) All the iRMX 86 System Call External Declaration Include files are 
on this diskette: 


hcrccn.ext 
hgtcmd.ext 
hgtopn.ext 
hsneor ,ext 
iaclos .ext 
iadlf l.ext 
iagtf s .ext 
iarnf l.ext 
iatrun.ext 
idlusr ,ext 
igttim.ext 
ilatdv.ext 
isatfl.ext 
iscrf l.ext 
isgtcs .ext 
isrdmv.ext 
istioj ,ext 
istusr ,ext 
iwtio.ext 
Isovly ,ext 
ncrext ,ext 
ncrseg.ext 
ndlcmp .ext 
ndlreg.ext 
ndsabl.ext 
nendln.ext 
ngtexh.ext 
ngtsiz ,ext 
nluobj .ext 
nrcuni ,ext 


hdlccn.ext 
hgticn.ext 
hgtpar .ext 
hstpbf .ext 
iacrdr .ext 
iagtcs .ext 
iagtpc.ext 
iaseek.ext 
iawrit .ext 
iexio j ,ext 
igtusr .ext 
ildtdv.ext 
ischac.ext 
isctcn.ext 
isgtf s .ext 
isrnf l.ext 
istpfx.ext 
isuncn.ext 
lalioj .ext 
nacctl.ext 
ncrjob.ext 
ncrsem.ext 
ndlext ,ext 
ndlseg.ext 
ndsdln.ext 
nenint ,ext 
ngjtlev.ext 
ngttok.ext 
nof f sp ,ext 
nrsint ,ext 


hfmtex.ext 
hgtipn.ext 
hsncmd.ext 
iaatf l.ext 
iacrfl.ext 
iagtde.ext 
iaopen.ext 
iaspec.ext 
icrioj .ext 
igtlds ,ext 
ihdtdv.ext 
ipatdv.ext 
isclos .ext 
isdlcn.ext 
islucn.ext 
isseek.ext 
istrun.ext 
iswrmv.ext 
laload.ext 
nalcmp .ext 
ncrmbx.ext 
ncrtsk.ext 
ndljob.ext 
ndlsem.ext 
neinit .ext 
nexint ,ext 
ngtpat .ext 
ngttyp ,ext 
nrcctl.ext 
nrstsk.ext 


hgtchr .ext 
hgtocn.ext 
hsneor , ext 
iachac.ext 
iadlcn.ext 
iagted.ext 
iaread.ext 
lasted. ext 
icrusr .ext 
igtpf x.ext 
iinusr ,ext 
ipdtdv.ext 
iscrdr ,ext 
isdlf l.ext 
isopen, ext 
isspec.ext 
isttim.ext 
iupdat .ext 
Islioj ,ext 
neremp .ext 
ncrreg.ext 
nctob j ,ext 
ndlmbx.ext 
ndltsk.ext 
nenabl.ext 
nfrcdl.ext 
ngtpri.ext 
ninemp .ext 
nremes .ext 
nsgex.ext 
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nsgint ,ext 

nsleep ,ext 

nsnctl.ext 

nsnmes ,ext 

nsnuni.ext 

nstexh.ext 

ns tint ,ext 

nstosx.ext 

nstpmn.ext 

nstpri.ext 

nsutsk.ext 

nucob j .ext 

nwtint .ext 

ualloc.ext 

ua tach.ext 

uchac.ext 

uchext ,ext 

uclose.ext 

ucreat .ext 

udcex.ext 

udctim.ext 

udelet ,ext 

udetac.ext 

uexit .ext 

uflinf .ext 

ufree.ext 

ugtarg.ext 

ugtcs .ext 

ugtexh.ext 

ugtsid.ext 

ugtsiz .ext 

ugttim.ext 

uopen.ext 

uovly ,ext 

uread.ext 

urenam.ext 

ursiom.ext 

useek.ext 

uspecl.ext 

uswbf .ext 

utrapc.ext 

utrpex.ext 

utrunc.ext 

uwrite.ext 


5) Three of the iRMX 86 R6.0 ICU System definition files are on thi 
diskette, 

rl8603.def 

rl8651.def 

rI8848.def 
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APPENDIX E 
DIRECTORY STRUCTURE 
OF THE START-UP SYSTEM 


This section shows you the Start-Up system directory structure that 
exists after you have successfully Installed the operating system. This 
Start-Up directory is in Figure E-1, 



] » directory 
y\ = data file 
L » list access 
R « read access 


N s no access 


OLAC = all access 


Figure E-1, Start-Up System Directory Structure 
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HARDWARE-RELATED PARAMETERS 


*** 




** * 

*** 




*** 

*** 

Interrupts 


*** 

*** 

(MPS) 

Master PIC Port Separation [O-OFFH] 

0002H 

*** 

*** 

(SIL) 

Slave Interrupt Levels [0-7/ None] 

None 

*** 

*** 

(LSS) 

Level Sensitive Slaves [0-7/None] 

None 

*** 

*** 

(PLI) 

80186 Level Sensitive Ints [4-5/None] 

None 

*** 

*** , 




,*** 

**** f 

Enter 

Changes [Abbreviation ?/= new value] : 


j **** 

» **** 1 

! 



j **** » 




» ******** ***:«t:ilc****5%*****:*c****:«{**:>r ;**:%*:*:****:<?:*? ****5%**:V*:%********* * 


lAPX 186 INITIALIZATION SCREEN 

This screen allows you to configure the iAPX 186 or iAPX 188 logic that 
provides programmable chip-select generation for memories and 
peripherals. Refer to the iAPX 186 HIGH INTEGRATION 16-BIT 
MICROPROCESSOR Data Sheet for information about these parameters. 


***** f 
» **** 


(UCW) 

(UCR) 

(LCS) 

(LCW) 


(PC A) 
(PCM) 
(LPW) 
(LPR) 
(UPW) 
(UPR) 
(PL A) 


**** ! Enter Changes [Abbreviation ?/= new_value] 
* **** ? 


**** 


^ ************************************************ *****:fc***:%****^ 
****************************************************************** 
j *■*** » 

**** » iAPX 186 Initialization 
***» (ucs) Upper CS Size [ 0400H-040000H] 

Upper CS Wait States [0, 1,2,3] 

Upper CS Wait for Ready [Yes/No] 

Lower CS Size [ 0,040 OH-0400 OH] 

Lower CS Wait States [0,1, 2,3] 

(LCR) Lower CS Wait for Ready [Yes/No] 

(MCS) Midrange CS Size [0,0200H-080000H] 

(MCA) Midrange CS Base Address [O-OFEOOOH] 

(MCW) Midrange CS Wait States [0,1,2, 3] 

(MCR) Midrange CS Wait for Ready [Yes/No] 

(PCS) Peripheral CS Active [Yes/No] 

Peripheral CS Base Address [O-OFCOOH] 

Peripheral CS Mapped to Memory [Yes/No] 

Lower Peripheral CS Wait States [0,1, 2, 3] 

Lower Peripheral CS Wait for Ready [Yes/No] 

Upper Peripheral CS Wait States [0, 1,2,3] 

Upper Peripheral CS Wait for Ready [Yes/No] 

Peripheral CS 5,6 Latch A1,A2 [Yes/No] 

* ** . 


00000400H 
000 OH 
Yes 

0000000 OH 
OOOOH 
No 

OOOOOOOOH 
OOOOOOOOH 
OOOOH 
No 
Yes 
OOOOH 
No 
000 2H 
Yes 
000 2H 
Yes 
No 


^*** 
! **** 


! **** * 


****************************************************************** 
’ ************************************************************** ’ 
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****************************************:*:******************************* 
* (UCS) Upper CS Size [0400H-040000H] 00000400H * 

it**** *************************** ********i(:*********** ******:%************* 

You must specify the size of the upper meimory chip select line. The 
value you specify must be IK (400H), 2K (800H), 4K (lOOOH), 8K (2000H), 
16K (4000H), 32K (8000H), 64K (lOOOOH), 128K (20000H) , or 256K (40000H). 
If you are using the iSBC 186/03 or the iSBC 186/51 processor board, it 
is recommended that you use the default value. If you are using the 
iSBC 188/48 processor board, change the default value to lOOOOH. 

The upper limit defined by this chip select line is always FFFFFH, The 
lower limit is ascertained by the ICU as the upper limit less the value 
specified for this parameter line. 


************************************************************************ 

* (UCW) Upper CS Wait States [0, 1,2,3] OOOOH * 

* *********************************************************************** 

You must specify the number of wait states for all accesses to the upper 
memory chip select line. The value you select can be from zero to 
three. If you are using the iSBC 186/03, the iSBC 186/51, or the 
iSBC 188/48 processor board, it is recommended that you use the default 
value . 


************************************************************************ 

* (UCR) -Upper CS Wait for Ready [Yes/No] Yes * 

* *********************************************************************** 

You must select whether or not the iAPX 186 should ignore external READY 
for the upper memory chip select line. If you specify "Yes", the 
iAPX 186 will wait for the number of wait states specified or will wait 
for an external READY condition. If you specify "No", the iAPX 186 will 
wait for the number of wait states specified but will not wait for an 
external READY condition. If you are using the iSBC 186/ 03, the 
iSBC 186/51, or the iSBC 188/48 processor board, it is recommended that 
you use the default value. 


************************************************************************ 

* (LCS) Lower CS Size [ 0,040 OH-040000] OOOOOOOOH * 

************************************************************************ 

In response to the "Lower CS Size" parameter line you must specify a 
value of zero or the size of the lower memory chip select line. The 
value of zero indicates that you do not Intend to program the lower 
memory chip select line. -Any non-zero value you specify must be IK 
(400H), 2K (800H), 4K (lOOOH), 8K (2000H), 16K (4000H), 32K (8000H), 64K 
(lOOOOH), 128K (20000H), or 256K (40000H), If you are using the 
ISBC 186/03, the iSBC 186/51, or the iSBC 188/48 processor 
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board, it is recommended that you use the default value. The lower limit 
defined by this chip select line is always OOOOOH. The upper limit is 
ascertained by the ICU as the lower limit plus the value specified for 
this parameter line. 


***:>{*** ********:%**** ******5lc*********ifc*:*f:Sf**** ********************* ******* 

* (LCW) Lower CS Wait States [0, 1,2,3] OOOOH * 

************************************************************************ 

If you specified a non-zero value for the "Lower CS Size" parameter line, 
you must specify the number of wait states for all accesses to the lower 
memory chip select line. The value you select can be from zero to 
three. If you are using the iSBC 186/03, the iSBC 186/51, or the 
iSBC 188/48 processor board, it is recommended that you use the default 
value. 


************************************************************************ 

* (LCR) Lower CS Wait for Ready [Yes /No] No * 

************************************************************************ 

If you specified a non-zero value for the "Lower CS Size" parameter line, 
you must select whether or not the iAPX 186 should ignore external READY 
for the lower memory chip select line. If you specify "Yes", the 
iAPX 186 will wait for the number of wait states specified or will wait 
for an external READY condition. If you specify "No", the iAPX 186 will 
wait for the number of wait states specified but will not wait for an 
external READY condition. If you are using the iSBC 186/03, the 
iSBC 186/51, or the iSBC 188/48 processor board, it is recommended that 
you use the default value. 


***********************:>cl!(:A;:jlf:fc:fc:^**:fc**:A;************************************ 

* (MCS) Midrange CS Size [ 0,02000H-080000H] OOOOOOOOH * 

************************************************************************ 

In response to the "Midrange CS Size" parameter line you must specify a 
value of zero or the size of the midrange memory chip select line. The 
value of zero indicates that you do not intend on programming the 
midrange memory chip select line. Any non-zero value you specify must be 
8K (2000H), 16K (4000H), 32K (8000H), 64K (lOOOOH), 128K (20000H), 256K 
(40000H) , or 512K (80000H),, If you are using the iSBC 186/03, the 
iSBC 186/51, or the ISBC 188/48 processor board, it is recommended that 
you use the default value. 

The iAPX 186 provides four midrange memory chip select lines. Your 
response to this parameter sets the total size of the memory block 
defined by the four midrange select lines. The size of any one midrange 
memory chip select line is one-fourth of the total. The lower limit 
defined by this chip select line is defined by the "Midrange Chip Select 
Base Address". The upper limit is ascertained by the ICU as the lower 
limit plus the value specified for this parameter line. 
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*************:*?*******:*?**** ***********:%************ ******:fc************** * 

* (MCA) Midrange CS Base Address [O-OFEOOOH] OOOOOOOOH * 

****** *******************:fc*:*f***/(***:fe**************;<:;<t**;fe*:fc:lf ************** 

If you specify a non-zero value for the "Midrange CS Size" parameter 
line, you must specify the base address of the midrange memory chip 
select lines. Otherwise, specify a value of zero. If you are using the 
iSBC 186/03, the iSBC 186/51, or the iSBC 188/48 processor board, it is 
recommended that you use the default value. 

You must set the base address at any integer multiple of the size of the 
total memory block selected. For example, if you specified a total block 
size of 32K for the previous parameter (MCS), you must select a base 
address of lOOOOH or 18000H but not 14000H. 

If you specify MCS=080000H for the previous parameter line, you must also 
specify the base address to be OOOOOH and the "Lower CS Size" parameter 
to be zero. 


************************************************************************ 

* (MCW) Midrange CS Wait States [0, 1,2,3] 000 OH * 

* *********************************************************************** 

If you specified a non-zero value for the "Midrange CS Size" parameter 
line, you must specify the number of wait states for all accesses to the 
midrange memory chip select lines. Otherwise, specify a value of zero. 
The value you select can be from zero to three. If you are using the 
iSBC 186/03, the iSBC 186/51, or the iSBC 188/48 processor board, it is 
recommended that you use the default value. 


************************************************************************ 

* (MCR) Midrange CS Wait for Ready [Yes/No] No * 

************************************************************************ 

If you specified a non-zero value for the "Midrange CS Size" parameter 
line, you must select whether or not the lAPX 186 should ignore external 
READY for the midrange memory chip select lines. Otherwise, specify a 
value of zero. If you specify "Yes", the iAPX 186 will wait for the 
number of wait states specified or will wait for an external READY 
condition. If you specify "No", the iAPX 186 will wait for the number of 
wait states specified but will not wait for an external READY condition. 
If you are using the iSBC 186/03, the iSBC 186/51, or the iSBC 188/48 
processor board, it is recommended that you use the default value. 
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The module with the highest address. Since the Root Job module is always 
the last module the second stage of the ICU locates, the information we 
need to complete this table must come from the R00T.MP2 file. The 
contents from a sample R00T.MP2 file is shown in Figure 15-2. 


INPUT FILE: CROOT.LNK 
OUTPUT FILE: ROOT 

CONTROLS SPECIFIED IN INVOCATION COMMAND: 

TO ROOT SEGSIZE(STACK(0)) ORDER(CLASSE S(DATA, STACK) ) 
PRINT(R00T.MP2) ADDRESSES(CLASSES(CODE( 029FF0H) ,DATA(02A4B0H) ) ) 
INITCODE(029FF0H) OC(NOCM ,NOSB) PC(NLOI ,PL,NOXM,NOSB) OOD 

• 

MEMORY MAP OF MODULE RBEGIN 

MODULE START ADDRESS PARAGRAPH = 29FFH OFFSET = 000 OH 
SEGMENT MAP 


START 

STOP 

LENGTH ALIGN 

NAME 

CLASS 

~>29FF0H 

2A2F3H 

0304H 

W 

CODE 

CODE 

2A2F4H 

2A2FFH 

001 2H 

W 

SAB DESCRIPTOR 

,Q 

CODE 

— >2A300H 

2A3C5H 

00C6H 

W 

U J DESCRIPTOR 

»c 

CODE 

— >2A4B0H 

2A4C1H 

001 2H 

W 

D 

DATA 

DATA 

2A4C2H 

2A5EDH 

012CH 

W 

INIT STACK 

STACK 

2A5EEH 

2A5EEH 

000 OH 

W 

STACK 

STACK 

2A5F0H 

2A5F0H 

OOOOH 

G 

??SEG 


2A5F0H 

2A5F0H 

000 OH 

W 

MEMORY 

MEMORY 


GROUP MAP 

ADDRESS GROUP OR SEGMENT NAME 
2A4B0H DGROUP 
DATA 

29FF0H CGROUP 
CODE 

SABJDESCRIPTORS 
U J DESCRIPTORS 


Figure 15-2. ROOT.MP2 File 
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The lines marked with arrows in Figure 15-2 contain the sample 
information we need to complete the table. Since the ICU has organized 
the modules in the order shown in Figure 15-3, we can also estimate the 
other needed stop addresses. (Note that the Root Job's data and stack 
segments should be treated as one block of RAM.) 


Root Job Data and Stack 

2A5EDH 

2A4B0H 

Root Job Code 


2A3C5H 

29FF0H 

Other Operating 

System Data 

? 

29BA0H 

Other Operating 

System Code 

? 

1040H 


Figure 15-3. A Sample KAM-Based System 


The following start addresses summarize this sample information. 


System Module 

lOS 

HI 

NUCLEUS 

SDB 

EIOS 

LOADER 

UDI 

ROOT 


Code Locations 

001040H- ? 
011620H- ? 
0177C0H- ? 
01D7A0H- ? 
022740H- ? 
025AA0H- ? 

02803 0H-029B9FH 
029FF0H-02A3C5H 


Data Locations 

029F30H- ? 
029EB0H- ? 
029FC0H- ? 
029BA0H- ? 
029FE0H- ? 
029FA0H- ? 
029F80H-029FEFH 
02A4B0H-02A4C1H 


Having determined the basic size requirements of the system's code and 
data segments, we can approximate the RAF[ and ROM requirements of this 
sample ROM-based system. Figure 15-4 shows how we can configure our 
sample ROM-based system. 


NOTE 

All data segments must be in RAM. All 
RAM and ROM code must start on a 16 
byte boundaries. 
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Root Job Code 


Boundary +28F35H 


Boundary +28B5FH 
Other Operating System Code 
16K byte Boundary 


15CDH 


Root Job Data 


Other Operating System Data 


1490H 

148FH 

1040H 


Figure 15-4. A Sample ROM- Based System 


Before the system code is burned into ROM, it is recommended that you 
test your ROM-based system in RAM, To do this, invoke the ICU and 
respond to the "ROM" prompt with a RAM address in the "Memory" screen. 
The following screen shows the changes in our sample configuration. 


:k‘k4c:k^‘k^ic:kirk:k'kicirki(^i{i(:k'k^^^^:k:k:kick‘k-k^'k4fk-k'k^icit:k'k"k^^:k:k:ki(:k'k^'/(:ki(ick'ic:k:k'ki<:k:k 


j -kicic-k ♦ 

***** I 

kkkk * 

* **** 

kkk • 

* *** 

kkk 

*** 

kkk 

** * 


Memory 

Type : RAM = low, high 
Type : ROM = low, high 


First define your RAM blocks in paragraphs 
Type : RAM = 0104H, DFFFH 

f d 

Type : RAM = 0104h, Offfh 


Type : RAM = 

Now define your ROM blocks in paragraphs 


Type : ROM = 100 Oh, 38F5h 


Type : ROM = 

*** , 

^*** 

**** j 

f **** 

* **** j 

j **** * 
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Running the second stage of the ICU reveals that our sample ROM-based 
system would have the following RAM addresses: 


System Module 

lOS 

HI 

NUCLEUS 

SDB 

EIOS 

LOADER 

UDI 

ROOT 


Code Locations 

OlOOOOH- ? 
0205E0H- ? 

026 78 OH- ? 
02C760H- ? 
031700H- ? 
034A60H- ? 
036FF0H- ? 
038B60H-038F35H 


Data Locations 

0013D0H- ? 

00 135 OH- ? 

001 46 OH- ? 

00 104 OH- ? 
001480H- ? 

001 44 OH- ? 
001420H- ? 
001490H-0015CDH 


The last steps you need to take to create a ROM-based system include: 

• Use LIB86 to put all generated system modules into the system 
library for boot loading or dowr-loading. 

• Load and test your ROM-based system in RAM, 

• Invoke the ICU to give the "Memory" screen actual ROM addresses. 

• Generate your configuration files to link and locate your new 
system. 

• Record the Start and Stop addresses of each module to be burned 
into ROM. This information is found in the memory maps LOC86 
generates for each module. 

• Burn your code into ROM. 

Appendix C illustrates how to burn your Nucleus code into ROM. Refer to 
this appendix for more information. 
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